`query_interactions`¶

Execute a MongoDB aggregation pipeline against evaluated interactions. Use for analytics: counts, averages, trends, leaderboards, filtering, grouping.

The collection (compass_interaction_profiles) stores one document per evaluated interaction with these queryable fields:

Top-level fields: - session_id (string) — unique ID for this interaction. ALWAYS include in $project for search results. - agent_name (string) — agent who handled the call - created_dt (datetime) — when the interaction occurred - interaction_driver (string) — why the customer called (e.g. 'Account Inquiry') - interaction_direction (string) — 'inbound' or 'outbound' - title (string) — short description of the interaction - language_primary (string) — e.g. 'en' - customer_display_name (string) — the customer/caller's display name (may be 'Unknown') - session_metadata.company_name (string) — the client/company name associated with this interaction. Use for grouping by client, filtering by company, or finding calls for specific accounts. - session_metadata.customer_display_name (string) — customer's name from session metadata - session_metadata.location (string) — store/site location name - session_metadata.audio_length_seconds (float) — call duration in seconds - session_metadata.store_id (string) — store identifier

Compass Score (PRIMARY quality metric): - stage0.predicted_objective (float 1.0-5.0) — overall interaction quality. >= 3.5 is positive. - DIFFERENT from CSAT (below) — Compass Score = quality vs. rubric, CSAT = customer satisfaction. - A call can have high CSAT but low Compass Score (or vice versa).

Predicted CSAT: - stage0.predicted_csat (float 1.0-5.0) — LLM-predicted customer satisfaction. >= 4 is positive. - Use ONLY when the user specifically asks about customer satisfaction; otherwise prefer Compass Score.

Agent Lift (components.outcome_lift): - components.outcome_lift.lift (float) — agent's contribution to outcome - components.outcome_lift.lift_band — 'strong_positive', 'positive', 'neutral', 'negative', 'strong_negative', 'insufficient_data' - components.outcome_lift.is_scorable (boolean)

Signals (components.signals.items[]): - signal_key, value ('present'|'absent'|'unclear'), confidence Filter with $elemMatch on components.signals.items.

Guidance (components.guidance.items[]): - guide_key, value, guidance_kind ('opportunity'|'excellence'), priority ('p0'|'p1'|'p2'), description

Scores (components.scores.items[]): - key, value, meta.score_kind ('overall'|'outcome'), meta.lift (outcome only)

Dimensions (components.dimensions[]): - key (e.g. 'dim.outcome_quality'), value, confidence

Trust (components.trust): - level ('high'|'medium'|'low'), score

Talk Patterns (components.talk_patterns.summary): - total_duration_s, hold_count, total_hold_time_s, interruption_count, talk_time_ratio, avg_response_time_ms

Transcript: - interaction.messages[].text / .actor. Text index on interaction.messages.text for $text $search.

IMPORTANT: - Do NOT include project_id in your pipeline — it is injected automatically. - Only evaluable interactions are queried. - created_dt is a BSON Date — use ISODate strings like '2026-01-01T00:00:00Z'. - ALWAYS include session_id in search/list results so you can generate deep links.

Parameters¶

Parameter	Type	Required	Default	Description
`pipeline`	array	yes	—	MongoDB aggregation pipeline stages.
`explanation`	string	no	—	Brief explanation of what this query does (for audit).

Example call¶

from fastmcp import Client
from fastmcp.client.auth import BearerAuth

async with Client(
    "https://mcp.chordia.ai/mcp",
    auth=BearerAuth("YOUR_APPLICATION_KEY"),
) as client:
    result = await client.call_tool(
        "query_interactions",
        {
            "pipeline": []
        },
    )
    print(result.content[0].text)
# Plus any of the 1 optional params from the table above.

In Claude Desktop, Cursor, or any MCP-aware client the same call is issued by the LLM automatically once the server is configured — see integrations.

Result¶

Success responses are JSON of the shape below. Optional fields are omitted when the underlying data isn't present.

{
  "rows": [
    {"_id": "Alpha Agent", "avg_score": 3.71, "n": 86},
    {"_id": "Beta Agent", "avg_score": 3.42, "n": 64}
  ],
  "count": 2,
  "pipeline_summary": "$match → $group → $sort (limit 50)"
}

Auth context¶

Every call receives the connection's project_id and access_scope automatically — the caller never passes them. See Authentication & RBAC for how scope narrows results.

Errors¶

All tools return JSON. Errors are wrapped in { "error": "..." }. The most common shapes are documented in Python integration → Error shape.

query_interactions¶