exploring-mcp-intent-clusters

Exploring MCP intent clusters

Intent clustering takes the free-text $mcp_intent values agents attach to their tool calls, embeds them, and groups semantically similar goals into clusters. Attribution is per call: each call is credited to its own intent (calls without one inherit the most recent prior intent in the same session), so a tool's counts reflect the intent it actually served. Each cluster carries its tool distribution, call counts, and error rates — answering "what are people trying to do, and does it work?" rather than "which tool was called". The snapshot also carries a tool-centric pivot answering the reverse question: for a given tool, which intents drive its usage, how often do agents find it, and who does it compete with.

Unlike tool quality and sessions (which ultimately aggregate $mcp_tool_call), clustering needs embeddings and is not expressible in SQL. It is served by two typed tools backed by a stored snapshot.

Tools

Workflow: read the current clusters

posthog:mcp-analytics-intent-clusters-retrieve
{}

Returns a snapshot with status, last_computed_at, computed_with (the embedding model, clustering parameters, and sample-coverage percentages), a clusters array, a tools array (the tool pivot), and tool_overlaps. Each cluster has a label, intent_count, call_count, error_count, error_rate_pct, routing_entropy, a tool_distribution (which tools that goal routes to, with per-tool error rates), sample_intents, plus switches (errored call immediately followed by a different tool for the same intent — the strongest "agents mix these tools up" evidence) and self_retries (errored call immediately retried with the same tool — a sign the tool's error messages aren't helping agents self-correct).

Read clusters by call_count for "what are agents mostly doing", or by error_rate_pct for "which goals are failing" — a high error rate on a cluster points at a class of agent goals the tools serve badly.

routing_entropy is how spread-out a cluster's tool usage is: low entropy means one goal reliably maps to one tool; high entropy means agents are casting around for the right tool for that goal (often a missing-capability signal).

Workflow: answer "is my tool discoverable?" from the tool pivot

Each entry in tools carries:

• clusters — the intent clusters the tool serves, each with capture_pct (its share of the cluster's calls), rank, top_competitor (the strongest other tool and its share), and description_fit (cosine similarity between the tool's description and the cluster centroid; null until descriptions are captured). Entries carry only cluster_id, not the cluster's own label or totals — join them against the top-level clusters array on that id
• n_clusters_served — how many clusters the tool serves in total. The entry list above is capped, so compare the two before saying "this tool serves N intents"
• discovery_rate_pct — of the sampled sessions whose $mcp_tools_list catalog advertised the tool, the share that actually called it; null when the tool was advertised in fewer than 5 sampled sessions
• contested_score — call-weighted mean entropy of its clusters: how often its intents are split with other tools

High description_fit with low capture_pct is the discoverability failure: agents should find the tool for that intent but pick something else. Low fit with high capture means the description undersells what the tool actually does. tool_overlaps lists pairs competing for the same intents; use sessions_with_both vs sessions_with_either to separate workflows (used together) from confusion (one or the other).

Read coverage before quoting numbers: computed_with.sampled_sessions / session_coverage_pct say how much of the window the corpus represents, and advertisement_coverage_pct bounds what discovery rates can see. Only sessions with an observed tools-list catalog enter discovery denominators, and sessions in exec-wrapper mode advertise only the wrapper, so per-tool discovery is measured on full-catalog sessions.

computed_with is not a completeness check for everything, though. Only the top-level tool and overlap-pair caps report what they dropped, via dropped_tools and dropped_overlap_pairs. The per-cluster lists are capped silently, so treat a cluster showing 10 switches or 5 self-retries as "at least that many", not "exactly". A tool's cluster entries are capped too, but there n_clusters_served gives you the real count.

Clustering reads events only. The on-demand session summaries (MCPSession.intent, what "generate intent" writes) are deliberately left out: a summary describes a whole session, and spreading it across that session's calls is the mis-attribution the per-call corpus exists to remove. So a session whose intent was only ever summarised is not in any cluster — check intent_coverage_pct for how much of the window that leaves out, and read session summaries directly when you need them.

Workflow: handle an empty or stale snapshot

• Empty / idle with no clusters (status: idle, clusters: []): no run has happened yet. Trigger one (below) and tell the user it computes in the background.
• Stale last_computed_at: offer to recompute.

Workflow: recompute

posthog:mcp-analytics-intent-clusters-recompute
{}

Returns immediately with status: computing (HTTP 202); the work runs in the background. Poll posthog:mcp-analytics-intent-clusters-retrieve until status returns to idle (done) or error. Don't block waiting — tell the user to re-ask in a minute.

Constructing UI links

• Intent clustering: https://app.posthog.com/project/<project_id>/mcp-analytics/intent-clustering

Tips

• Clusters are only as good as the $mcp_intent coverage — if few calls carry an intent, clusters will be sparse; cross-check intent coverage with a quick countIf(toString(properties.$mcp_intent) != '') over $mcp_tool_call
• A cluster with high error_rate_pct plus high routing_entropy is the strongest "the tools don't serve this goal well" signal — worth a closer look at its sample_intents and tool_distribution
• Recompute is throttled to one run at a time per project; a 202 while already computing just re-confirms the in-flight run

Related skills

• exploring-mcp-tool-quality — per-tool error rates and latency
• exploring-mcp-sessions — the individual runs behind the intents