eval-mcp

MCP ツールを評価する

ツールの説明はプロンプトエンジニアリングの一部です。説明は Claude のコンテキストウィンドウに直接入り、Claude が適切な引数で適切なツールを選ぶかどうかを左右します。このスキルを使えば、ツールの品質を勘に頼るのではなく、測定して改善できます。

前のレベルを土台として、3 段階でテストします。

1. 静的解析 — 決定論的なスキーマ品質チェック（Claude への呼び出しなし）
2. 選択テスト — Claude は各インテントに対して適切なツールを選ぶか？
3. 説明の最適化 — 混同のパターンに基づく反復的な改善

適用するタイミング

• ユーザーが自身の MCP ツールのスキーマが適切に設計されているか確認したい場合
• ユーザーが、Claude がユーザーのインテントに対して適切なツールを選択するかテストしたい場合
• ユーザーがツールの混同をデバッグしている場合（Claude が間違ったツールを選ぶ）
• ユーザーが選択精度を高めるためにツールの説明を最適化したい場合
• ユーザーが build-mcp-server でのひな形作成を終え、品質を検証したい場合

ワークフローの概要

Phase 1: Connect → Phase 2: Static Analysis → Phase 3: Selection Testing → Phase 4: Optimize
                                                            ↑__________________________|

フェーズ 4 ではループします。書き換えを適用 → スキーマを再取得 → 再テスト → 精度を比較します。

前提条件

• Node.js >= 18 — MCP Inspector CLI（npx）に必要です
• jq — スキーマ解析スクリプトに必要です
• 実行中の MCP サーバー — サーバーが tools/list に応答する必要があります。まず build-mcp-server/scripts/test-server.sh を使って接続を確認してください。

---

フェーズ 1 — 接続と一覧作成

ユーザーの MCP サーバーに接続し、ツールのスキーマを取得します。

1a：接続情報の取得

サーバーへの接続方法をユーザーに尋ねます。

• HTTP/SSE：URL（例：http://localhost:3000/mcp）
• stdio：起動コマンド（例：node dist/server.js）

1b：ツールのスキーマを取得

bash scripts/fetch-tools.sh <url-or-command> <transport> <workspace>/tools.json

MCP Inspector CLI を介して tools/list を呼び出し、スキーマを保存します。

1c：一覧を表示

概要テーブルを表示します。

| # | Tool | Description (preview) | Params | Annotations |
|---|------|-----------------------|--------|-------------|
| 1 | search_issues | Search issues by keyword... | 3 | readOnlyHint |
| 2 | create_issue | Create a new issue... | 4 | — |

ツール数を判定します。1～15 は最適、15～30 は注意、30 以上は過剰です（search+execute パターンを検討してください）。

1d：ワークスペースを作成

スキルディレクトリの隣、またはユーザーのプロジェクト内に {server-name}-eval/ としてワークスペースを作成します。

{server-name}-eval/
├── tools.json
├── evals/
│   └── evals.json
└── iteration-N/

---

フェーズ 2 — 静的解析

決定論的な品質チェックを実行します。Claude への呼び出しは不要です。開発中にすぐフィードバックが得られます。

2a：解析を実行

bash scripts/analyze-schemas.sh <workspace>/tools.json <workspace>/iteration-N/static-analysis.json

2b：結果を表示

ツールごとの品質スコアを表示します。チェック対象の基準については、references/quality-checklist.md を参照してください。

| Tool | Desc | Params | Schema | Annotations | Overall | Issues |
|------|------|--------|--------|-------------|---------|--------|
| search_issues | 3/3 | 3/3 | 2/3 | 2/3 | 2.5 | No negation |
| create_issue | 1/3 | 1/3 | 0/3 | 0/3 | 0.5 | 4 issues |

2c：類似するツールのペアを判定

説明の重複度が高いツールが解析で見つかった場合は、混同のリスクとして強調します。

### Sibling Pairs (confusion risk)
| Tool A | Tool B | Overlap | Risk |
|--------|--------|---------|------|
| search_issues | list_issues | 52% | HIGH |

2d：判断ポイント

重大な問題（説明がない、アノテーションがゼロ）がある場合は、フェーズ 3 の前に修正することを推奨します。静的な問題は選択テストにノイズを生みます。まず明白な問題を修正し、その後で見極めにくい問題を測定してください。

すべてのツールのスコアが良好であれば、フェーズ 3 に進みます。

---

フェーズ 3 — 選択テスト

Claude が各ユーザーインテントに対して適切なツールを選ぶかテストします。これが評価の中核です。

3a：テスト用インテントを生成

インテント生成のパターンについては、references/eval-patterns.md を参照してください。

各ツールについて、次を生成します。

• 起動すべきインテントを 3 つ — 直接的、暗黙的、くだけた表現
• 起動すべきでないインテントを 2 つ — 惜しい表現とキーワードの重複

フェーズ 2 で判定された類似するツールの各ペアについて、次を生成します。

• ツールごとに曖昧さを解消するインテントを 1 つ — Claude が適切な類似ツールを選ぶかテストします

すべてのインテントをユーザーに提示して確認してもらいます。追加、削除、変更するものがあるか尋ねます。

3b：インテントを保存

{workspace}/evals/evals.json に保存します。

{
  "server_name": "my-server",
  "generated_from": "tools.json",
  "intents": [
    {
      "id": 1,
      "intent": "Are there any open bugs related to checkout?",
      "expected_tool": "search_issues",
      "type": "should_trigger",
      "target_tool": "search_issues",
      "notes": "Implicit intent — doesn't name the action"
    }
  ]
}

3c：選択テストを実行

各インテントについて、次の情報を受け取るサブエージェントを起動します。

1. tools.json にある完全なツールスキーマ（Claude のコンテキストに表示される形式）
2. ユーザーのインテント文
3. ツールを 1 つだけ選び、引数を提示するか、適合するツールがなければ選択を見送るよう指示する内容

サブエージェントへのプロンプト：

You have access to the following MCP tools:

{tool schemas as JSON}

A user sends this message:
"{intent text}"

Which tool would you call? Respond with JSON:
{
  "selected_tool": "tool_name" or null,
  "arguments": { ... } or {},
  "reasoning": "One sentence explaining your choice"
}

If no tool fits the user's request, set selected_tool to null.
Select exactly ONE tool. Do not suggest calling multiple tools.

各結果を {workspace}/iteration-N/selection/intent-{ID}/result.json に保存します。

効率化のため、すべての選択テストを並列で起動します。

3d: 評価結果

bash scripts/grade-selection.sh \
  <workspace>/iteration-N/selection \
  <workspace>/evals/evals.json \
  <workspace>/iteration-N/benchmark.json

3e: 結果を表示

## Selection Results — Iteration N

**Accuracy:** 82% (41/50 correct)

| Metric | Count |
|--------|-------|
| Correct | 41 |
| Wrong tool | 5 |
| False accept | 2 |
| False reject | 2 |

### Per-Tool Accuracy
| Tool | Precision | Recall |
|------|-----------|--------|
| search_issues | 0.90 | 0.85 |
| create_issue | 1.00 | 1.00 |

### Worst Confusions
| Expected | Selected Instead | Times |
|----------|-----------------|-------|
| list_issues | search_issues | 3 |
| get_user | find_user_by_email | 2 |

---

Phase 4 — 最適化と反復

混同パターンを分析し、説明の改善案を提案します。書き換えのパターンについては、references/optimization.md をお読みください。

4a: 混同を分析

混同された各ペア（worst_confusions から取得）について、次の作業を行います。

1. 両方のツールの現在の説明を読みます
2. 混同の原因を特定します（否定表現の欠落、対象範囲の重複、相互参照の欠如など）
3. optimization.md の区別パターンに従って、具体的な書き換え案を作成します

4b: 提案を提示

## Suggested Improvements

### search_issues ↔ list_issues (confused 3 times)

**search_issues — Before:**
> Search issues by keyword.

**search_issues — After:**
> Search issues by keyword across title and body. Returns up to `limit` results ranked by relevance. Does NOT filter by status, assignee, or date — use list_issues for structured filtering.

**Reason:** Adding scope boundary and cross-reference to disambiguate from list_issues.

{workspace}/iteration-N/suggestions.json に保存します（形式は optimization.md で定義されています）。

4c: 適用して再テスト

ユーザーが MCP サーバーのコードに書き換えを適用した後、次の作業を行います。

1. サーバーを再起動します
2. Phase 1 を再実行して tools.json を再取得します（説明が変更されている可能性があります）
3. Phase 2 を再実行して静的解析を更新します
4. 同じ evals.json を使用して、Phase 3 を iteration-N+1 に対して再実行します
5. 精度を比較します。

## Iteration Comparison

| Metric | Iteration 1 | Iteration 2 | Delta |
|--------|------------|------------|-------|
| Accuracy | 82% | 94% | +12% |
| search↔list confusion | 3 | 0 | -3 |

4d: 反復に関するガイダンス

• 改善の要因を特定できるよう、1 回の反復につき兄弟ツールのペアを 1 つ変更します
• 精度が頭打ちになった場合、残る混同の解消にはアーキテクチャの変更（ツールの統合、名前変更、またはツール構成の再編成）が必要な可能性があります
• 精度が 90％を超えるか、残る混同が人間でも判断に迷うような曖昧なエッジケースになった時点で終了します

---

参照ファイル

該当するフェーズに進んだときに、これらをお読みください。事前に読む必要はありません。

• references/quality-checklist.md — ツールスキーマのテスト可能な品質基準（Phase 2）
• references/eval-patterns.md — ツール選択テスト用インテントの作成方法（Phase 3）
• references/optimization.md — 評価結果に基づく説明の改善方法（Phase 4）

関連スキル

• build-mcp-server — MCP サーバーの設計とスキャフォールディング（最初に実行し、その後 eval-mcp で検証します）
• build-mcp-app — インタラクティブな UI ウィジェットを備えた MCP サーバー