exploring-mcp-tool-quality

探索 MCP 工具质量

任何使用 PostHog 的 MCP analytics SDK 进行埋点的 MCP 服务，都会在 Agent 每次调用工具时，在共享的 events 表中发出一个 $mcp_tool_call 事件。没有专用的 ClickHouse 表——每个字段都作为 events 上的 $mcp_* 属性存储，而每项工具质量指标（错误率、延迟 百分位数、覆盖范围）都是对这一个事件进行聚合的结果。这些数据构成了 MCP 分析仪表板和工具质量页面的基础。

优先使用治理指标

对于任何 MCP 失败率的核心指标，在使用类型化工具或 SQL 配方之前，先调用 posthog:metric-list 并查找 mcp_tool_call_fail_pct。如果该指标已获批准且未发生漂移，就用 posthog:data-catalog-metric-run 运行它，并将结果作为规范的核心指标。如果用户还询问哪些工具导致了失败，先运行核心指标，再使用以下工作流进行细分，并标明该细分结果不是规范指标。如果没有匹配的治理指标，请说明目录中没有匹配项，并将派生的比率标记为非规范指标。

对于单个工具，优先使用类型化工具——posthog:query-mcp-tool-stats（调用次数、 错误数、p50/p95、用户数、会话数、意图数）、posthog:query-mcp-tool-failures（按执行框架统计的主要错误 消息），以及 posthog:query-mcp-tool-daily-stats（逐日趋势）。每个工具都接受 toolName + dateRange，并运行与工具详情 界面相同的查询运行器——无需手写 SQL。

跨工具问题应使用 HogQL 和 posthog:execute-sql——下面的“哪个工具错误最多”排名没有对应的类型化工具，因此请先用 SQL 排名，再用 posthog:query-mcp-tool-stats 和 posthog:query-mcp-tool-failures 深入分析错误最多的工具。完整的 属性架构和既定查询配方都在共享的 MCP 数据参考中： products/posthog_ai/skills/querying-posthog-data/references/models-mcp.md。 该参考是 $mcp_* 架构以及下文使用的有效工具名称写法的唯一事实来源——为方便起见，本技能仅内嵌了非规范的 “哪个工具错误最多”细分查询；请从参考中获取矩阵、延迟和执行框架查询配方，而不要重新推导。编写查询前请先阅读该参考。

最重要的两条规则

• 始终使用有效工具名称。 新版 SDK 事件会将实际工具包装在一次单次执行调用中，因此按原始 $mcp_tool_name 分组会把所有内容都归到包装工具下。请使用：

  coalesce(nullIf(toString(properties.$mcp_exec_tool_call_name), ''), toString(properties.$mcp_tool_name))
  

• 始终通过 toBool(...) 读取 $mcp_is_error，并通过 toFloat(...) 转换 $mcp_duration_ms。这些属性都是字符串。

始终设置时间范围——否则这些查询会扫描整个 events 表。

工作流：哪个工具的错误率最高（非规范细分）

对于“哪个工具错误最多”的细分，按错误 率为工具排名，但要通过设置调用量的 HAVING 下限来防止小样本噪声：

posthog:execute-sql
SELECT
    coalesce(nullIf(toString(properties.$mcp_exec_tool_call_name), ''), toString(properties.$mcp_tool_name)) AS tool,
    count() AS total_calls,
    countIf(toBool(properties.$mcp_is_error)) AS errors,
    round(countIf(toBool(properties.$mcp_is_error)) * 100.0 / count(), 1) AS error_rate_pct
FROM events
WHERE event = '$mcp_tool_call'
    AND coalesce(nullIf(toString(properties.$mcp_exec_tool_call_name), ''), toString(properties.$mcp_tool_name)) != ''
    AND timestamp >= now() - INTERVAL 30 DAY
GROUP BY tool
HAVING total_calls >= 20
ORDER BY error_rate_pct DESC, total_calls DESC
LIMIT 20

同时报告比率和数量——3 次调用中错误率为 100% 通常并不能说明实际情况；50,000 次调用中错误率为 12% 才更有参考价值。可以提议进一步查询错误最多工具的 $mcp_error_message 值（见下文）。

工作流：工具质量矩阵

每个工具占一行，展示错误率、延迟百分位数和覆盖范围——与工具质量页面相对应。可直接运行的查询位于 models-mcp.md 中的“工具质量矩阵”一节。

工作流：为什么工具会失败

对于某个工具按运行环境分组的主要失败类别，调用 posthog:query-mcp-tool-failures 并传入 toolName——它是下方查询的类型化等效形式。失败数据来自与错误率相同的来源：发生错误的 $mcp_tool_call 事件（$mcp_is_error），按有效工具名称进行筛选。失败按 $mcp_error_type 分组（语义类别：internal、validation、api_4xx、api_5xx、permission、timeout、rate_limited、missing_context），并在存在 HTTP $mcp_error_status 时按其分组。若要查看某个类别中的单次错误调用——包括捕获的 $mcp_error_message、会话 ID、运行环境和意图——将该类别的原始 error_type/error_status 传给 posthog:query-mcp-tool-failure-occurrences （在消息捕获功能上线前捕获的事件中，$mcp_error_message 为空）：

posthog:execute-sql
SELECT
    concat(
        coalesce(nullIf(toString(properties.$mcp_error_type), ''), 'unknown'),
        if(empty(coalesce(toString(properties.$mcp_error_status), '')), '',
           concat(' (HTTP ', coalesce(toString(properties.$mcp_error_status), ''), ')'))
    ) AS failure,
    count() AS n
FROM events
WHERE event = '$mcp_tool_call'
    AND toBool(properties.$mcp_is_error)
    AND coalesce(nullIf(toString(properties.$mcp_exec_tool_call_name), ''), toString(properties.$mcp_tool_name)) = '<tool>'
    AND timestamp >= now() - INTERVAL 30 DAY
GROUP BY failure ORDER BY n DESC LIMIT 10

$mcp_error_type 仅在较新的 SDK/服务端路径中填充——部分错误调用既没有类型也没有状态，因此会归入 unknown 类别。

工作流：最慢的工具

将聚合指标替换为延迟百分位数 （quantile(0.95)(toFloat(properties.$mcp_duration_ms))），并按 p95_ms 排序。矩阵查询已返回 p50_ms / p95_ms。

构建 UI 链接

• 仪表板：https://app.posthog.com/project/<project_id>/mcp-analytics/dashboard
• 工具质量：https://app.posthog.com/project/<project_id>/mcp-analytics/tool-quality

始终提供 UI 链接，方便用户直观验证。

提示

• 同时报告错误率和调用量；设置 HAVING total_calls >= N 下限，避免调用量很少的工具意外排到列表顶部
• 仅在用户要求时才从延迟百分位数中排除错误调用——失败调用往往耗时最长，排除它们会掩盖问题
• $mcp_client_name 可用于按运行环境细分质量（Claude Code 与 Cursor 等）；规范的分组 multiIf 位于 models-mcp.md
• 运行环境分组由 products/mcp_analytics/backend/mcp_harness.py 在服务端解析——它是权威来源，而 posthog:query-mcp-harness-breakdown 会执行该逻辑。如果你手写的 SQL 与界面结果不一致，说明你的分组逻辑与 mcp_harness.py 不一致；请优先使用类型化工具，而不是重新推导分组逻辑

相关技能

• exploring-mcp-sessions — 深入查看 单次 Agent 运行及其工具调用顺序
• exploring-mcp-intent-clusters — 对 Agent 目标进行分组，并查看哪些意图导致错误