improving-mcp-tools

MCP ツールの改善

MCP サーバーを改善できているかどうかは、測定できる場合に限って判断できます。このスキルはキャンペーンの手順です。現在のエージェント体験を評価し、最大の問題を修正し、再評価して、数値で妥当性が示された変更だけをリリースします。これは「MCP を改善する」ループの運用マニュアルです。1 回のパスで 1 つの反復を実施し、後の反復や別のエージェントが作業をやり直さずに再開できるよう、記録を残します。

目的関数

services/mcp/evals/ がハーネスです。benchmark/tasks.yaml には、expected_tools と success_criteria を含む固定のエージェントタスクが定義されています。スコアを比較できるのは、同じベンチマークの version の実行間に限られます。

• プローブモード（決定論的、LLM なし）： services/mcp/ から LIVE_MCP_URL=... LIVE_MCP_TOKEN=... pnpm exec tsx evals/runner/probe.ts --out score.json を実行します。 ツールの存在に関する見落とし（見つけやすさ）、プローブの失敗、レイテンシの p50／p95 を報告します。終了コードが 0 以外の場合はリグレッションです。
• エージェントモード（LLM によるリプレイ＋評価者）：タスクの成功率とツール選択の精度を評価します。説明や見つけやすさの変更にはこのモードを使います。エージェントが誤ったツールを選ぶ問題は、プローブでは検出できません。

ハーネスは、シード済みのローカル環境または devbox スタックに対して実行し、顧客のプロジェクトに対しては絶対に実行しないでください。ローカルでの手順は次のとおりです。NODE_ENV=development PORT=9876 POSTHOG_API_BASE_URL=http://localhost:8000 pnpm dev:hono を実行し、個人用 API キーを LIVE_MCP_TOKEN として使用します。

1 回の反復

1. 測定します。 ベースラインを得るためにハーネスを実行します。MCP アナリティクスツール（query-mcp-tool-stats、query-mcp-tool-failures、query-mcp-tool-descriptions、query-mcp-tool-sample-intents）と、signals scout クックブックの分析方法（products/signals/skills/signals-scout-mcp-tool-calls/references/queries.md）を使って、本番環境のエビデンスを取得します。失敗のランキング、リトライ／苦戦の状況、レイテンシ、どのツールにも一致しなかったインテントを確認します。
2. 問題を 1 つ選びます。 影響範囲 × 深刻度で順位を付けます。ジャーナルに失敗が 2 回記録されているものはスキップします。1 回の反復につき問題は 1 つです。複数の問題を修正する PR では、スコアが変化したときに、どの修正の効果か特定できません。
3. 範囲を絞って修正します。 以下の許可リストにあるファイルだけを対象にします。一般的な修正例：適切なインテントからツールを見つけやすくなるよう説明を明確にする、エージェントが繰り返し誤る入力スキーマを厳密にする、アノテーションを修正する、スキルを更新する。
4. 検証します。 影響を受けるベンチマークのスライスと、リグレッションがないことを確認するためのサンプルを再実行します。対象の指標が改善し、他の指標が悪化しなかった場合にのみ変更を維持します。変更を破棄することも通常の結果です。その内容をジャーナルに記録して、次に進みます。
5. リリースします。 反復ごとに PR を 1 つ作成し、本文に変更前と変更後のスコアを記載します（形式はreferences/campaign-journal.mdを参照）。スタンプ可能な状態に保ちます。変更行数は 400 行以下とし、以下の許可リスト内のファイルだけを対象にし、stamphog ラベルを適用します。自律性のレベルはキャンペーン設定で決まります。デフォルトは人によるレビュー用のドラフト PRです。オペレーターが自動運転の実験を明示的に有効にした場合に限り、自動マージを有効にします（ガードレールを参照）。
6. ジャーナルに記録します。 パスを終了する前に、反復の記録を追記します。

厳格なガードレール

これらは提案ではありません。いずれかに違反すると、キャンペーンの審査は不合格になります。

• 許可リスト — キャンペーンの PR で変更できるのは、次のものに限られます：products/*/mcp/tools.yaml、 products/*/skills/**、services/mcp/evals/**、pnpm generate-tools / scaffold-yaml のコード生成出力（services/mcp/src/tools/generated/** と services/mcp/schema/generated-tool-definitions.json）、およびドキュメント。 それ以外（ハンドラーコード、パッケージマニフェスト、ワークフロー、マイグレーション、認証関連のパス）に触れる場合は、作業を中止し、その指摘をドラフト PR またはレポートとして人間に引き継いでください。
• データへの読み取り専用アクセス。 ハーネスとすべての本番クエリは読み取り専用です。測定中に、顧客に見えるオブジェクトを作成、変更、削除してはいけません。
• 証拠がなければ、実施したことになりません。 ベースラインスコア、変更後のスコア、使用したハーネスコマンドの正確な内容がそろわない PR は作成しないでください。
• ベンチマークの整合性。 検証対象の修正と同じ PR で benchmark/tasks.yaml を編集してはいけません。試験問題と解答を同時に変えても、何も証明できません。ベンチマークの変更は別の PR とし、version を引き上げてください。
• 上限。 オペレーターが定めたイテレーション数、トークン数、PR 数の上限を守ってください（デフォルトでは、未マージのキャンペーン PR が 3 件になった時点で停止します）。1 つの課題で 2 回失敗した場合、その課題は今後対象にしません。
• 緊急停止スイッチ。 キャンペーン設定、その機能フラグ、またはオペレーターから停止の指示があった場合は、イテレーションの途中でも停止し、状態を記録して、正常に終了してください。

想定される失敗パターン

• あるインテントに役立つ説明の変更が、別のインテントに適したツールからトラフィックを奪うことがあります。そのため、リグレッションのないサンプルが必須です。インテントクラスターのスナップショットに含まれる tool_overlaps（exploring-mcp-intent-clusters を参照）には、どのインテントでどのペアが競合するかが正確に記載されています。説明を書き換える前にスナップショットを取得し、変更後に再計算してください。重複するペアのキャプチャに変化があれば、リグレッションの兆候として扱ってください。
• スタックのウォーム状態によってプローブのレイテンシーは変動します。レイテンシーの変化を修正によるものと判断する前に、3 回以上の実行で中央値を比較してください。
• ツールが見つからない場合、カタログに存在しないのではなく、機能フラグによるゲーティングが原因かもしれません。検出可能性を「修正」する前に、getToolsForFeatures のゲーティングを確認してください。