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

| Tool | Purpose |

| ------------------------------------------------- | ------------------------------------------------- |

| posthog:mcp-analytics-intent-clusters-retrieve | Fetch the latest cluster snapshot for the project |

| posthog:mcp-analytics-intent-clusters-recompute | Trigger an async recompute of the snapshot |

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