exploring-mcp-intent-clusters

探索 MCP 意图簇

意图聚类会获取 Agent 在工具调用中附加的自由文本 $mcp_intent 值，将其转换为嵌入向量，并按语义相似度将目标分组成簇。归因按调用计算：每次调用都归入自己的意图（没有意图的调用会继承同一会话中最近一次较早的意图），因此工具的计数反映的是它实际服务的意图。每个簇都包含工具分布、调用次数和错误率，从而回答“人们_想要_做什么，以及能否成功？”而非“调用了哪个工具”。快照还包含一个以工具为中心的透视视图，用来回答相反的问题：对于给定工具，哪些意图推动了它的使用，Agent 多常能找到它，以及它与哪些工具存在竞争。

与工具质量和会话不同，后两者最终会汇总 $mcp_tool_call；聚类需要嵌入向量，无法通过 SQL 实现。它由两个基于已存储快照的类型化工具提供。

工具

工具	用途
posthog:mcp-analytics-intent-clusters-retrieve	获取项目的最新簇快照
posthog:mcp-analytics-intent-clusters-recompute	异步触发快照重新计算

工作流：读取当前簇

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

返回的快照包含 status、last_computed_at、computed_with（嵌入模型、聚类参数和样本覆盖率百分比）、clusters 数组、tools 数组（工具透视视图）以及 tool_overlaps。每个簇都有 label、intent_count、call_count、error_count、error_rate_pct、routing_entropy、tool_distribution（该目标会路由到哪些工具，以及各工具的错误率）、sample_intents，此外还有 switches（出错的调用后立即针对同一意图改用不同工具的情况，是 Agent 混淆这些工具的最有力证据）和 self_retries（出错的调用后立即使用同一工具重试，表明该工具的错误消息没有帮助 Agent 自行纠正）。

按 call_count 读取簇，可了解“Agent 主要在做什么”；按 error_rate_pct 读取，则可了解“哪些目标正在失败”。某个簇的错误率较高，说明工具无法妥善服务一类 Agent 目标。

routing_entropy 表示某个簇的工具使用分散程度：熵值较低，意味着某个目标稳定地对应一个工具；熵值较高，则意味着 Agent 正在四处尝试，为该目标寻找合适的工具（通常表明缺少相应能力）。

工作流：根据工具透视图回答“我的工具是否容易被发现？”

tools 中的每个条目都包含：

• clusters — 该工具服务的意图簇，每个簇包含 capture_pct （该工具在此簇调用中的占比）、rank、top_competitor（份额最高的 其他工具及其占比）和 description_fit（工具描述与簇中心点之间的余弦相似度； 尚未采集描述时为 null）。条目仅包含 cluster_id，不包含簇自身的标签或总量—— 请根据此 ID 将其与顶层 clusters 数组中的条目关联起来
• n_clusters_served — 该工具总共服务的簇数。上面的条目列表有上限，因此在说“此工具服务 N 个意图”之前，请先比较这两个值
• discovery_rate_pct — 在 $mcp_tools_list 目录中列出了该工具的抽样会话里，实际调用该工具的占比；如果列出该工具的抽样会话少于 5 个，则为 null
• contested_score — 该工具各簇熵的加权平均值（按调用量加权）：其意图与其他工具共同承担的频率

description_fit 高但 capture_pct 低，说明该工具未能被发现： Agent 本应为该意图找到此工具，却选择了其他工具。description_fit 低但 capture_pct 高，说明描述没有充分体现工具的实际功能。 tool_overlaps 列出针对相同意图彼此竞争的工具对；请对比 sessions_with_both 与 sessions_with_either，以区分工作流（同时使用）和混淆（一者或另一者）。

引用数字前，请先查看覆盖率：computed_with.sampled_sessions / session_coverage_pct 表示语料覆盖了多大比例的时间窗口，advertisement_coverage_pct 则限定了发现率能够反映的范围。只有观察到工具列表目录的会话才会计入发现率分母；在 exec-wrapper 模式下，会话只公布包装器，因此每个工具的发现率只根据完整目录会话进行衡量。

不过，computed_with 并不能检查所有数据是否完整。只有顶层工具和重叠工具对的数量上限会通过 dropped_tools 和 dropped_overlap_pairs 报告被省略的数量。每个簇中的列表会静默截断，因此，如果某个簇显示 10 次切换或 5 次自行重试，应视为“至少这么多”，而非“恰好这么多”。工具的簇条目也有上限，但其中的 n_clusters_served 会提供实际数量。

聚类只读取事件。按需生成的会话摘要 （MCPSession.intent，即“generate intent”所写入的内容）会被有意排除： 摘要描述的是整个会话，将其分摊到该会话的各次调用中，正是逐次调用语料要消除的错误归因。因此，如果某个会话的意图只被写入摘要，它就不会出现在任何簇中——请查看 intent_coverage_pct，了解这会导致多大比例的时间窗口未被覆盖；需要时请直接阅读会话摘要。

工作流：处理空快照或过期快照

• 空 / 尚未运行，且没有簇（status: idle，clusters: []）：尚未运行过。请触发一次运行（见下文），并告知用户计算将在后台进行。
• last_computed_at 过期：提供重新计算选项。

工作流：重新计算

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

立即返回 status: computing（HTTP 202）；任务将在后台运行。轮询 posthog:mcp-analytics-intent-clusters-retrieve，直到 status 返回 idle（完成）或 error。不要阻塞等待——请告知用户一分钟后重新提问。

构造 UI 链接

• 意图聚类：https://app.posthog.com/project/<project_id>/mcp-analytics/intent-clustering

提示

• 聚类效果取决于 $mcp_intent 的覆盖率——如果很少有调用携带意图，聚类结果就会很稀疏；可通过对 $mcp_tool_call 执行快速查询 countIf(toString(properties.$mcp_intent) != '')，交叉检查意图覆盖率
• error_rate_pct 高且 routing_entropy 也高的聚类，是“工具无法很好地满足此目标”这一信号中最明显的；值得进一步查看其 sample_intents 和 tool_distribution
• 每个项目一次只能运行一个重新计算任务；如果已有任务正在计算，此时返回 202 只会再次确认该任务仍在运行

相关技能

• exploring-mcp-tool-quality — 每个工具的错误率和延迟
• exploring-mcp-sessions — 意图背后的各次 运行