exploring-mcp-intent-clusters

MCP インテントクラスターの分析

インテントクラスタリングでは、エージェントがツール呼び出しに付与するフリーテキストの $mcp_intent 値を埋め込み、意味的に類似した目標をクラスターにグループ化します。アトリビューションは呼び出しごとに行われます。インテントがない呼び出しには、同じセッション内の直前のインテントが引き継がれるため、ツールのカウントには、そのツールが実際に対応したインテントが反映されます。各クラスターには、ツールの分布、呼び出し回数、エラー率が含まれます。これにより、「どのツールが呼び出されたか」ではなく、「人々は何を しようとしている のか、それはうまくいっているのか」という問いに答えられます。スナップショットには、逆の問いに答えるツール中心のピボットも含まれています。特定のツールについて、どのインテントがその利用を促しているか、エージェントがそのツールをどのくらいの頻度で見つけているか、どのツールと競合しているかを確認できます。

ツールの品質やセッションの分析（最終的には $mcp_tool_call を集計するもの）とは異なり、クラスタリングには埋め込みが必要で、SQL では表現できません。保存済みスナップショットを基に、型付きツールが 2 つ提供されています。

ツール

ツール	用途
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（エラーになった呼び出しの直後に、同じインテントで別のツールが呼び出されたケース。エージェントがこれらのツールを取り違えていることを示す最も強い証拠）と、self_retries（エラーになった呼び出しの直後に同じツールで再試行されたケース。ツールのエラーメッセージがエージェントの自己修正に役立っていない兆候）が含まれます。

「エージェントが主に何をしているか」を確認するには call_count で、「失敗している目標」を確認するには error_rate_pct でクラスターを読み取ります。クラスターのエラー率が高い場合、そのクラスターはツールがうまく対応できていないエージェントの目標群を示しています。

routing_entropy は、クラスター内でツールの利用先がどの程度分散しているかを表します。エントロピーが低い場合、1 つの目標は安定して 1 つのツールに対応します。エントロピーが高い場合、エージェントはその目標に適したツールを探し回っています（多くの場合、機能が不足している兆候です）。

ワークフロー：「自分のツールは見つけてもらえるか？」にツールのピボットから答える

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 が低い場合、見つけてもらいにくい状態です。 エージェントはそのインテントに対してツールを見つけるはずなのに、別のツールを選んで います。fit が低く capture が高い場合、説明がツールの実際の機能を十分に伝えていません。 tool_overlaps には、同じインテントをめぐって競合するペアが一覧表示されます。 sessions_with_both と sessions_with_either を比較して、ワークフロー（併用）と 混乱（どちらか一方が使われる）を区別してください。

数値を引用する前に、カバレッジを確認してください。computed_with.sampled_sessions / session_coverage_pct は、対象期間のうちコーパスがどの程度を表しているかを示し、 advertisement_coverage_pct は discovery rate で確認できる範囲の上限を示します。 ツール一覧カタログが観測されたセッションのみが discovery の分母に含まれます。また、 exec-wrapper モードのセッションではラッパーのみが提示されるため、ツールごとの discovery は、完全なカタログがあるセッションを対象に測定されます。

ただし、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）を直ちに返し、処理はバックグラウンドで実行されます。 status が idle（完了）または error になるまで posthog:mcp-analytics-intent-clusters-retrieve をポーリングしてください。処理の完了を 待たず、1 分後にもう一度質問するようユーザーに伝えてください。

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 を詳しく確認する価値があります。
• 再計算はプロジェクトごとに同時に1回までに制限されています。すでに計算中に返される 202 は、実行中の処理を再確認するだけです。

関連スキル

• exploring-mcp-tool-quality — ツールごとのエラー率とレイテンシ
• exploring-mcp-sessions — インテントの背後にある個々の実行