exploring-mcp-tool-quality

MCP ツールの品質を調べる

PostHog の MCP 分析 SDK を組み込んだ MCP サーバーは、エージェントがツールを呼び出すたびに、共有の 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 を指定します。ツール詳細 UI と同じクエリランナーを実行するため、SQL を手書きする必要はありません。

ツールをまたぐ質問には、posthog:execute-sql による HogQL を使用します。以下の「最もエラーが多いツールはどれか」というランキングには型付きツールがないため、まず SQL でランキングし、その後、最も問題のあるツールを posthog:query-mcp-tool-stats と posthog:query-mcp-tool-failures で詳しく調べてください。完全なプロパティスキーマと確立されたクエリのレシピは、共有 MCP データリファレンスにあります。 products/posthog_ai/skills/querying-posthog-data/references/models-mcp.md。 このリファレンスは、以下で使用する $mcp_* スキーマと実効ツール名のイディオムに関する唯一の信頼できる情報源です。このスキルには、便宜上、非公式な「最もエラーが多いツールはどれか」という内訳のみを掲載しています。マトリックス、レイテンシ、ハーネスのレシピは、再導出せずにリファレンスから取得してください。クエリを書く前に必ず読んでください。

特に重要な2つのルール

• 常に実効ツール名を使用してください。 新しい 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 の上位値を取得することも提案してください（以下を参照）。

ワークフロー：ツール品質マトリックス

ツールごとに1行で、エラー率、レイテンシのパーセンタイル、リーチを表示します。ツール品質画面に対応する、すぐに実行できるクエリは models-mcp.md の「Tool-quality matrix」にあります。

ワークフロー：ツールが失敗する理由

あるツールで失敗数の多い分類（ハーネスごとにグループ化）を調べるには、toolName を指定して posthog:query-mcp-tool-failures を呼び出します。これは、以下のクエリに相当する型付きツールです。失敗はエラー率と同じソース、つまり有効なツール名で絞り込んだ、エラーが発生した $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 — 単一のエージェント実行と、そのツールの呼び出し順序を詳しく調べます。
• exploring-mcp-intent-clusters — エージェントの目標をグループ化し、どのインテントがエラーにつながっているか確認します。