Domain 2: Tool Design & MCP Integration

配点 18% — Task 2.1〜2.5

2.1 効果的なツール記述設計

🔑

Tool description はツール選択の唯一の主要機構

LLM は description を使ってツールを選択する。最小限の説明は類似ツール間の信頼性を低下させる。良い description には ① 入力フォーマット ② クエリの例 ③ エッジケース ④ 類似ツールとの境界 を含める。

❌ 最小限（試験の誤答パターン）	✅ 良い記述
`get_customer`: “Retrieves customer information” `lookup_order`: “Retrieves order details” → 類似 identifier format で誤選択発生	`get_customer`: “顧客 ID またはメールでアカウントを検索・確認。返金・変更処理の前に必ず呼ぶ。注文照会には lookup_order を使うこと” → 境界・使い分けが明確

2.2 構造化エラーレスポンス

`errorCategory`	説明	`isRetryable`
`transient`	タイムアウト・サービス一時停止	`true`
`validation`	不正な入力・形式エラー	`false`
`permission`	権限不足・アクセス拒否	`false`
`business`	ポリシー違反（$500 超の返金等）	`false`

⚠️

access failure vs valid empty result の区別（頻出）

access failure（タイムアウト）→ isRetryable: true でエラーを明示的に返す
valid empty result（マッチなし）→ 成功として空リストを返す

混同するとコーディネーターが誤判断。「空リストを成功で返す」は anti-pattern。

2.3 ツール粒度設計（fine-grained vs coarse-grained）

ツール設計でしばしば問われるのが「粒度」の判断です。「1 つの大きなツール」と「複数の小さなツール」のどちらが正解かは、シナリオ依存で判断する必要があります。

❌ 粗粒度すぎ（coarse-grained）	✅ 適切な分割
`manage_customer`: “顧客の作成・読取・更新・削除をすべて行う” 引数: `action: "create" \| "read" \| "update" \| "delete"` → どの操作が呼ばれたか LLM の判断に依存。削除を承認していないのに削除されるリスク	`get_customer`, `create_customer`, `update_customer`, `delete_customer` の 4 つに分割 → 各操作に個別に permission・hook を設定可能。`delete_customer` だけ人間承認を必須にできる

判断軸	細かく分ける（fine-grained）	まとめる（coarse-grained）
権限管理	操作ごとに承認・監査を変える必要がある	同じ権限レベルで使われる
エラーハンドリング	失敗時の挙動が操作ごとに違う	失敗パターンが共通
LLM の呼び出し精度	4〜8 個程度なら選択精度が高い	引数で分岐は誤選択の温床
retry 戦略	テーブルスキャンとレコード更新で個別に設計	同一 API ラッパーで十分

🔑

経験則：1 エージェントあたり 4〜8 ツール

マルチエージェントの場合、各サブエージェントが扱うツールは 4〜8 個に絞る。これを超えると LLM のツール選択精度が低下する。「すべてのエージェントに全ツールを与える」は罠 9（Top 10）の典型例。

2.4 MCP サーバー設定

スコープ：プロジェクト vs ユーザー

図2-1: MCP サーバースコープ設定ファイルの場所

Transport の選択（stdio / Streamable HTTP）

MCP 仕様 2025-11-25 では公式 transport が 2 種類：stdio と Streamable HTTP。第 3 の transport「HTTP+SSE 単独」は旧仕様（2024-11-05）の方式で、現在は deprecated（後方互換目的で残存。新規実装では選ばない）。

Transport	用途	実装形態	`.mcp.json` の指定	推奨度
stdio	ローカル MCP サーバー	npx 等で立ち上げる subprocess（stdin/stdout 経由 JSON-RPC）	`command` + `args` + `env`	✅ ローカル開発・CLI ツール統合の第一選択
Streamable HTTP	リモート / hosted MCP サーバー	単独の HTTP サーバー（POST + 必要に応じて SSE で stream）	`url` + `transport: "http"`	✅ 2025-11-25 spec の remote 公式標準。新規実装はこれ
HTTP+SSE 単独	旧仕様の hosted MCP	単独 SSE エンドポイント	`url` + （旧クライアントが SSE を仮定）	⚠️ deprecated（2024-11-05 仕様の遺物）

🔍

Streamable HTTP と「SSE 単独 transport」は別物

Streamable HTTP は「HTTP POST + 必要に応じて SSE で stream」という構造で、SSE をオプション機能として内包する transport。一方「SSE 単独 transport」は POST せず SSE だけで通信していた旧 transport。試験で SSE と HTTP の違いを問われたら、「SSE は Streamable HTTP の中で stream を返すときの形式の 1 つ。SSE 単独 transport は deprecated」 が正解。

stdio の設定例（ローカル subprocess）：


// .mcp.json — stdio
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

Streamable HTTP の設定例（hosted / SaaS 連携）：


// .mcp.json — Streamable HTTP（remote）
{
  "mcpServers": {
    "atlassian": {
      "url": "https://mcp.atlassian.com/v1",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer ${ATLASSIAN_TOKEN}"
      }
    }
  }
}

🧭

選択の判断軸

ローカルツール（git, ファイルシステム, データベースの dev インスタンス）→ stdio
SaaS 連携（Atlassian, Linear, Slack 等の hosted MCP）→ Streamable HTTP
既存の hosted MCP が SSE 単独で公開されている → 移行を促し、当面は接続できるなら接続（deprecated 警告は出る）

「全部 stdio で済ませる」は罠。SaaS 連携を stdio + 自前 proxy で実装すると、認証トークンの取り回しが複雑化し、複数クライアントから同時利用しづらくなる。

2.5 MCP の 3 プリミティブ（Academy コアコンテンツ）

📌

MCP 3 プリミティブの使い分け

プリミティブ	制御者	用途	例
Tools	モデルが制御	アクション実行（外部 API コール・データ取得）	`get_customer`, `search_web`
Resources	アプリが制御	読み取り専用データの公開・コンテンツカタログ	issue 一覧, DB スキーマ, ドキュメント階層
Prompts	ユーザーが制御	事前定義のワークフロー指示テンプレート	ドキュメントフォーマット, コードレビューフロー

MCP 高度機能（Advanced Topics コンテンツ）

機能	説明	試験との関連
Sampling	MCP サーバーがクライアント経由で LLM 呼び出しを要求する仕組み。本来の設計意図は「サーバー側で LLM が必要だが、API 契約・モデル選択・コスト負担はクライアント側に委譲する」というアーキテクチャ上の責務分離。副次効果としてサーバー実装者が API キー管理から解放される	D1 のサブエージェント設計と関連
Progress / Log 通知	長時間処理のリアルタイムフィードバック。context オブジェクトと logging コールバック	D5 のコンテキスト管理と関連
Roots	特定ディレクトリへのアクセス許可。セキュリティ境界とファイル探索の効率化	D2 ツール設計の原則に関連
Transport 選択	stdio（ローカル subprocess）vs Streamable HTTP（remote）の 2 種が公式。詳細は §2.4 Transport の選択を参照	D2 ツール設計の原則と直結

組み込みツールの選択基準

ツール	用途	選ぶべき場面
`Grep`	ファイル内容の検索	関数名・エラーメッセージ・import のパターン検索
`Glob`	ファイルパスのマッチング	拡張子・名前でファイルを検索（例: `*/.test.tsx`）
`Edit`	ユニークテキストで部分編集	明確にユニークな箇所の修正（失敗時は Read+Write にフォールバック）
`Read+Write`	ファイル全体の操作	Edit が非ユニークテキストで失敗した場合のフォールバック
`Bash`	コマンド実行	ビルド・テスト・スクリプト実行