exploring-mcp-tool-usage

MCP ツールの利用状況を調べる

@posthog/mcp SDK を組み込んだ MCP サーバーは、エージェントがツールを呼び出すたびに $mcp_tool_call イベントを発行します。このスキルは、MCP ツールの利用状況を調べたいものの、 具体的な質問がまだ決まっていないユーザー向けの最初の窓口です。以下のメニューを提示し、 選ばれた内容に答えるツール、または専用のスキルに案内してください。

まずはガバナンス対象の指標を確認

MCP の失敗率または割合について尋ねられた場合は、型付きツールや SQL のレシピを使う前に posthog:metric-list を呼び出し、mcp_tool_call_fail_pct を探してください。承認済みでドリフトのない一致項目について posthog:data-catalog-metric-run を実行し、正式な概要値を提示してください。失敗を引き起こすツールやハーネスについても尋ねられた場合は、まず概要値に答え、その後、以下のツール別ワークフローを使って正式な指標ではない内訳を示してください。一致するガバナンス対象の指標がない場合は、その旨を伝え、算出した率が正式な指標ではないことを明記してください。

ここにあるツール別ツールはすべて、toolName（有効なツール名。サーバー側で解決されるため、 エージェントが実際に呼び出す名前を渡します。ただし posthog:query-mcp-tool-failures は例外で、 $exception イベントに一致するため、生の登録名である $mcp_tool_name を渡します） と dateRange を受け取り、ツール詳細 UI と同じクエリランナーを実行します。 そのため、結果は UI と一致し、HogQL を手書きする必要はありません。

質問の例

ユーザーが何を尋ねればよいかわからない場合は、次の質問を最初に提示してください。

ユーザーへの質問…	回答するツール
「失敗が最も多い、または最も遅いツールは？」	exploring-mcp-tool-quality（すべてのツールを順位付け）、次に posthog:query-mcp-tool-stats で詳細を確認
「ツール X の全体的な状況は？」	posthog:query-mcp-tool-stats — 呼び出し数、エラー数、p50／p95、ユーザー数、セッション数、インテント
「ツール X の推移は？」	posthog:query-mcp-tool-daily-stats — 日ごとの時系列
「ツール X が失敗する理由は？」	posthog:query-mcp-tool-failures — 主なエラーメッセージをハーネス別に表示（生のツール名）
「ツール X を最もよく使うのは誰？」	posthog:query-mcp-tool-top-users — 主な呼び出し元（人物のメールアドレス／名前を含む）
「ツール X の呼び出しの直前／直後には何が呼び出される？」	posthog:query-mcp-tool-neighbors（neighborDirection: before／after）
「エージェントはツール X で何をしようとしている？」	posthog:query-mcp-tool-sample-intents — 最近のエージェントのインテント
「ツール X はどのような説明で登録されている？」	posthog:query-mcp-tool-descriptions — 確認された個別の説明
「どのハーネスが自分の MCP を使い、信頼性はどの程度？」	posthog:query-mcp-harness-breakdown — クライアント別の呼び出し数／エラー数／セッション数
「すべてのツールを通じて、エージェントは何をしようとしている？」	exploring-mcp-intent-clusters — 意味に基づく目標クラスター
「誰が接続していて、どの程度アクティブ？」	posthog:mcp-analytics-sessions-list — セッションごとの行とクライアントおよび人物
「このセッションでは何が行われた？」	exploring-mcp-sessions — 1 回のエージェント実行におけるツールの呼び出し順序

ツール名の特定

ツールごとのツールには toolName が必要です。ユーザーがツール名を指定した場合は、その名前を渡します。「どのツールが…」という大まかな質問の場合は、まず exploring-mcp-tool-quality を使ってツールを順位付けし、特に優れたツールを選んでから、上記のツールごとのツールで詳しく調べます。渡す名前は実効ツール名（単一実行のラッパー呼び出しの場合は内部ツール名）です。ツール品質の順位付けで返されるものと同じ文字列です。例外は posthog:query-mcp-tool-failures で、実効内部ツール名ではなく、生の $mcp_tool_name によって $exception イベントを照合します。

ツールごとのツールの使い方

ツール名と期間を指定して呼び出します。たとえば、ツールの主要な数値を取得する場合は次のとおりです。

posthog:query-mcp-tool-stats  { "toolName": "<tool>", "dateRange": { "date_from": "-7d" } }

その後、メニューから自然な次の質問を提案します。たとえば、posthog:query-mcp-tool-stats でエラー率が高いとわかったら posthog:query-mcp-tool-failures を使います。幅広く利用されているとわかったら、posthog:query-mcp-tool-top-users または posthog:query-mcp-tool-neighbors を使います。

SQL に切り替える場合

型付きツールで対応済み — 次の項目について SQL を手書きしないでください：

質問	ツール
あるツールの主要な数値	posthog:query-mcp-tool-stats
あるツールの日ごとの推移	posthog:query-mcp-tool-daily-stats
あるツールの主なエラー	posthog:query-mcp-tool-failures
あるツールを呼び出す主なユーザー	posthog:query-mcp-tool-top-users
あるツールの前後に呼び出されたツール	posthog:query-mcp-tool-neighbors
あるツールに対する最近のエージェントの意図	posthog:query-mcp-tool-sample-intents
あるツールに登録された説明	posthog:query-mcp-tool-descriptions
クライアントハーネス別の利用内訳	posthog:query-mcp-harness-breakdown
セッション一覧	posthog:mcp-analytics-sessions-list
あるセッションのツール呼び出し	posthog:mcp-analytics-sessions-tool-calls

未対応 — posthog:execute-sql を使います：

• ツールを横断した順位付け（ツール品質マトリックス —「最もエラーが多いツールはどれか？」）
• エラーが発生したセッションの絞り込み（セッション一覧にはエラーフィルターもエラー件数もありません）
• セッション内の実効ツール名（posthog:mcp-analytics-sessions-tool-calls は、生の $mcp_tool_name を返します。ラッパー呼び出しの内部ツール名ではありません）
• その他のカスタム内訳

上記の表にあるツールがツール一覧にない場合も、posthog:execute-sql を代替手段として使います。$mcp_tool_call を直接クエリしてください。スキーマとレシピは models-mcp.md にあります。

関連スキル

• exploring-mcp-tool-quality — エラー率／レイテンシ／利用範囲で ツールを順位付けしてから詳しく調べます
• exploring-mcp-sessions — 1 回のエージェント実行とそのツールの呼び出し順序
• exploring-mcp-intent-clusters — エージェントの目標を意味的な類似性に基づいてグループ化します