exploring-mcp-intent-clusters
探索PostHog MCP意图集群——按语义相似性分组的代理目标，包含每个集群的工具分布和错误率。当用户询问……时使用。
npx skills add https://github.com/posthog/ai-plugin --skill exploring-mcp-intent-clustersExploring 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. 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".
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 and clustering parameters), and a clusters array. 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), and sample_intents.
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: 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_intentcoverage — if few calls carry an intent, clusters will be sparse; cross-check intent coverage with a quickcountIf(toString(properties.$mcp_intent) != '')over$mcp_tool_call - A cluster with high
error_rate_pctplus highrouting_entropyis the strongest "the tools don't serve this goal well" signal — worth a closer look at itssample_intentsandtool_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 latencyexploring-mcp-sessions— the individual runs behind the intents