Architect Foundations ドメイン2: ツール設計と MCP 統合（18%）
この章で学ぶこと: ツールの説明文と境界の設計、構造化されたエラー応答、ツールの配分と tool_choice、MCP サーバーの設定（範囲、環境変数、リソース）、組み込みツールの選び方。
本番の60問のうち約11問が出ます。
| タスクステートメント | この章の節 |
|---|---|
| 2.1 明確な説明と境界を持つツールインターフェース | 第1節 |
| 2.2 MCP ツールの構造化エラー応答 | 第2節 |
| 2.3 ツールの配分と tool_choice | 第3節 |
| 2.4 MCP サーバーを Claude Code とエージェントに統合する | 第4節 |
| 2.5 組み込みツールの選び方 | 第5節 |
Developer Foundations で学んだ基本（ここでは繰り返しません）:
- ツール定義の項目（
name、description、input_schema、input_examples）と公式のベストプラクティス → Developer D8 第1.1〜1.2節 tool_choiceの4つの値と、新しいモデルでの制限 → Developer D8 第1.3節、Developer D5 第3.3節- MCP のしくみ（ホスト・クライアント・サーバー、ツール・リソース・プロンプト、通信方式） → Developer D8 第2節
- Claude Code の MCP の範囲（local / project / user） → Developer D8 第2.4節
is_errorの返し方 → Developer D4 第2.1節
1. ツールの説明と境界（2.1）
1.1 説明文がツール選択の主な手がかり
Claude はツールの説明文を読んで、どれを呼ぶか決めます。公式ドキュメントは「とても詳しい説明」を、ツールの性能に効く最も大事な要素としています（少なくとも3〜4文）。
説明に入れるもの:
| 項目 | 例（lookup_order） |
|---|---|
| 何をするか | 注文番号から、注文の内容・状態・配送先を返す |
| 入力の形式 | 注文番号は # と6桁の数字（例: #123456） |
| 問い合わせの例 | 「注文 #123456 はどこ？」「届いた商品が違う」 |
| 例外ケース | キャンセル済みの注文も返す。90日より前の注文は返さない |
| 似たツールとの境界 | 顧客の名前や連絡先を調べるときは get_customer を使う |
1.2 あいまい・重複した説明は誤った振り分けを生む
例: analyze_content（「内容を分析する」）と analyze_document（「文書を分析する」）。どちらを使えばよいか Claude にもわかりません。
| 直し方 | 例 |
|---|---|
| 名前と説明を変えて重なりをなくす | analyze_content → extract_web_results（Web 検索結果だけを対象と説明に書く） |
| 汎用ツールを目的別に分ける | analyze_document → extract_data_points、summarize_content、verify_claim_against_source |
「まとめる」と「分ける」の関係: 公式のベストプラクティスには「関係する操作は action パラメータで1つにまとめる」もあります（Developer D8 第1.2節）。どちらも目的は「どれを使うかをあいまいにしない」ことです。似たツールが散らばって迷うならまとめる。1つのツールの役割が広すぎて入出力がぶれるなら、決まった入出力の目的別ツールに分けます。
1.3 システムプロンプトがツール選択を上書きすることがある
例: システムプロンプトに「『分析』と言われたら、必ず詳しく分析すること」とある。すると「分析」という言葉に反応して、Web の結果にも analyze_document を呼ぶようになる。
よく書かれたツール説明があっても、キーワードに反応する指示がそれを上書きすることがあります。ツール選択がおかしいときは、ツールの説明と一緒にシステムプロンプトも見直します。
1.4 「最初の一手」として何を選ぶか
ツールの取り違えが起きたとき、最初にやることは「説明文を詳しくする」です。
| 選択肢 | 評価 |
|---|---|
| 説明文を詳しくする（入力形式、例、境界） | 根本原因に効き、手間が小さい。最初の一手 |
| few-shot 例を5〜8個足す | トークンが増え、根本原因（説明不足）が残る |
| キーワードで振り分ける層を前に置く | 作り込みすぎ。Claude の言葉の理解を使わなくなる |
| 2つのツールを1つにまとめる | 設計としてはありうるが、「最初の一手」としては手間が大きい |
2. 構造化されたエラー応答（2.2）
2.1 MCP の isError
MCP の仕様では、ツールのエラーは2種類です。
| 種類 | どう伝えるか | 例 |
|---|---|---|
| プロトコルのエラー | JSON-RPC のエラー | 存在しないツール、引数が不正、サーバーのエラー |
| ツール実行のエラー | ツール結果に isError: true |
外部 API の失敗、不正な入力データ、業務ルールのエラー |
ツール実行のエラーは結果としてモデルに届くので、モデルが読んで対処を考えられます。Messages API の tool_result では同じものを is_error: true と書きます。
2.2 エラーの4つの種類
| 種類 | 例 | 再試行 | エージェントがすべきこと |
|---|---|---|---|
| 一時的（transient） | タイムアウト、サービス停止 | できる | 待って再試行、または別の方法 |
| 検証（validation） | 注文番号の形式が違う | 入力を直せばできる | 入力を直す、顧客に聞き直す |
| 業務（business） | 返品期限を過ぎた、ポリシー違反 | できない | 理由を顧客に説明する、必要ならエスカレーション |
| 権限（permission） | この操作の権限がない | できない（そのままでは） | 権限のある流れへ回す |
「操作に失敗しました」だけの一律のエラーでは、どれなのかわかりません。エージェントは、むだな再試行をしたり、直せるのにあきらめたりします。
2.3 返す形の例
試験ガイドの例にならった形です。errorCategory や isRetryable は MCP の標準の項目ではなく、ツールの作り手が結果の中身として決める設計です。
{
"isError": true,
"content": [{
"type": "text",
"text": "{\"errorCategory\": \"business\", \"isRetryable\": false, \"message\": \"返品の受付期限（購入から30日）を過ぎています\", \"customerMessage\": \"申し訳ありません。この商品は返品期限を過ぎています。\"}"
}]
}
業務ルールの違反には、再試行できない（retriable: false）ことと、顧客に伝える説明を入れます。エージェントは同じ呼び出しをくり返さず、顧客に正しく伝えられます。
2.4 失敗 と 正当な空の結果
| アクセスの失敗 | 正当な空の結果 | |
|---|---|---|
| 意味 | 調べられなかった | 調べた結果、該当がなかった |
| 例 | 検索がタイムアウトした | 「その名前の顧客はいない」 |
| 返し方 | isError: true と失敗の種類 |
成功として、空の一覧と「0件」 |
| エージェントの判断 | 再試行するか、別の方法を試す | 「該当なし」として次に進む |
失敗を空の結果として返すと、エージェントは「存在しない」と誤って結論します。
2.5 どこで回復するか
- 一時的な失敗は、サブエージェントの中で回復する（再試行など）
- 解決できないエラーだけをコーディネーターに伝える。そのとき、試したこと、部分的な結果、考えられる代案も一緒に渡す（第5章 5.3 のエラー伝播）
3. ツールの配分と tool_choice（2.3）
3.1 ツールは多すぎないように
| 問題 | 例 | 対策 |
|---|---|---|
| ツールが多すぎて選択が不安定 | 1つのエージェントに18個 | 役割に必要な4〜5個に絞る |
| 専門外のツールを誤用する | 統合エージェントが自分で Web 検索を始める | そのエージェントから検索ツールを外す |
| 汎用ツールで何でもできてしまう | fetch_url でどんな URL でも読める |
文書の URL だけを検証して読む load_document に替える |
3.2 よく使う用途には、範囲を絞った横断ツール
例: 統合エージェントが事実確認のたびにコーディネーター経由で Web 検索エージェントを呼び、往復が増えている。確認の多く（例: 85%）は日付や名前などの簡単なもの。
- 統合エージェントに、簡単な確認だけをする
verify_factを渡す - 深い調査が必要な確認は、今までどおりコーディネーター経由で検索エージェントへ
全部の検索ツールを統合エージェントに渡すのは、役割の分離が崩れるので誤りです（最小権限の考え）。
3.3 tool_choice の使い方
| 値 | 意味 | 試験での使いどころ |
|---|---|---|
"auto" |
呼ぶかどうか Claude が決める。テキストだけ返すこともある | ふつうの会話 |
"any" |
必ずどれかのツールを呼ぶ | テキストではなく、必ずツール（構造化出力）を得たい |
{"type": "tool", "name": "extract_metadata"} |
指定したツールを必ず呼ぶ | 特定の処理を最初に必ず実行させる。続く手順は次のターンで |
"none" |
ツールを使わない | — |
新しいモデルでの変化（2026年11月時点）: 強制の
"any"と{"type": "tool"}は、手動の extended thinking を使うときと、Claude Opus 5.5・Sonnet 5.5・Fable 5.1・Mythos 5.1 では使えず、400 エラーになります。そのときの代わりは、"auto"とstrict: true（ツール入力がスキーマに合うことを保証）の組み合わせ、または固定の JSON の形が欲しいなら構造化出力（output_config.format）です。どのツールを使うかはプロンプトで導きます（Define tools: Forcing tool use）。試験ガイドの書き方は古い前提なので、試験では「強制」の考え方で答え、実務では使うモデルを確かめます。
4. MCP サーバーの統合（2.4）
4.1 範囲（どこに設定するか）
| 用途 | 試験ガイドの書き方 | 今の Claude Code |
|---|---|---|
| チームで共有するサーバー | プロジェクト単位: リポジトリの .mcp.json |
project スコープ: .mcp.json（コミットして共有） |
| 個人・実験用のサーバー | ユーザー単位: ~/.claude.json |
user スコープ（全プロジェクト）と local スコープ（このプロジェクトだけ）。どちらも ~/.claude.json に保存 |
試験では「チーム共有 = .mcp.json」「個人 = ~/.claude.json」と答えます。
4.2 秘密情報は環境変数展開で
{
"mcpServers": {
"github": {
"type": "http",
"url": "https://mcp.example.com/github",
"headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
}
}
}
（URL は説明用の例です）
.mcp.jsonはコミットするので、トークンを直接書かない${GITHUB_TOKEN}は、各開発者の環境変数から展開される（${VAR:-初期値}の形も使える）。展開はcommand、args、env、url、headersで使える- 安全のための注意: Claude Code は、
ANTHROPIC_API_KEYなど自分やクラウドの認証情報の変数を、リモートサーバーのurlとheadersでは空として扱う（プロジェクトの設定から認証情報が送られないように）。自分で名前を付けた変数を使う - 対話型のセッションでは、
.mcp.jsonのサーバーを初めて使う前に承認を求められる。claude -pや Agent SDK では確認なしで読み込まれるので、知らないリポジトリでは注意する
4.3 ツールは接続時に見つかり、同時に使える
設定したすべての MCP サーバーのツールは、接続したときに見つかり、同時に使えます。どのサーバーのツールを呼ぶかは、ツールの説明で決まります。ツールが多いときは、Claude Code のツール検索で必要なものだけ読み込まれます。
4.4 MCP ツールの説明で組み込みツールに負けないようにする
例: 社内の code_search MCP ツールは、シンボルの定義と参照を正確に返せる。でもエージェントは組み込みの Grep ばかり使う。
対策: MCP ツールの説明に、何ができるか、何を返すか、Grep より向いている場面（「関数の定義と全参照を、ファイル名と行番号付きで返す。名前の変更やリファクタリングの影響を調べるときは Grep ではなくこちらを使う」）を詳しく書きます。
4.5 既存のサーバーを先に探す
| 連携 | 選ぶもの |
|---|---|
| Jira、GitHub、Slack などの標準的なサービス | 既存の（信頼できる）コミュニティや公式の MCP サーバー |
| チーム固有のワークフロー（社内の承認の流れなど） | 自作の MCP サーバー |
公式の注意: 使うのは、自分で作ったサーバーか、信頼できる提供元のサーバーにします。
4.6 リソースで「中身の一覧」を見せる
MCP のリソースは、アプリが読み取り専用で渡すデータです。
| リソースの例 | 効果 |
|---|---|
| 課題の要約の一覧 | 「どんな課題があるか」を、検索ツールを何度も呼ばずにわかる |
| 文書の階層（目次） | どの文書を読めばよいか先にわかる |
| データベースのスキーマ | テーブル名を探すクエリが要らない |
探索のためのツール呼び出しが減り、エージェントは最初から全体を見渡せます。Claude Code では、リソースを @ で参照できます。
5. 組み込みツールの選び方（2.5）
5.1 どれを使うか
| ツール | 何をするか | 例 |
|---|---|---|
| Grep | ファイルの中身を検索（正規表現） | 関数 calculateTax の呼び出し元をすべて探す、エラーメッセージの場所 |
| Glob | ファイルのパスをパターンで探す | **/*.test.tsx のテストファイルを全部探す |
| Read | ファイル全体を読む | 見つけたファイルの中身を読む |
| Write | ファイル全体を書く | 新しいファイルを作る、全体を書き直す |
| Edit | 一意なテキストに一致した部分を置き換える | 1か所の修正 |
| Bash | コマンドを実行する | テストを動かす、git |
覚え方: 中身なら Grep、名前なら Glob。
5.2 Edit が失敗したら
Edit は、置き換える前の文字列がファイルの中で一意でないと失敗します（同じ行が何か所もある場合など）。
- 前後の行を含めて、一意になる文字列にしてもう一度 Edit する
- それでも一意な目印が見つからないときは、Read でファイル全体を読み、直した全体を Write で書く
5.3 少しずつ理解する
知らないコードベースで、最初に全ファイルを Read するのはむだです（コンテキストが埋まる）。
- Grep で入口を見つける（例: ルーティングの定義、
main） - Read でそのファイルを読み、import をたどる
- 必要なところだけ次を読む
5.4 ラッパーをまたぐ関数の追い方
例: utils/index.ts が formatDate を fmt という別名で再公開している。formatDate だけで Grep すると、fmt を使う場所を見落とす。
- まず、その関数が公開されている名前をすべて特定する（
export { formatDate as fmt }など） - 次に、それぞれの名前でコードベース全体を Grep する
6. 試験に向けたまとめ
| 問われ方 | 答えの考え方 |
|---|---|
| 似たツールの取り違え。最初の一手 | 説明文を詳しくする（入力形式、例、例外、境界） |
| 名前も説明もほぼ同じ2つのツール | 名前と説明を変える。汎用ツールは目的別に分ける |
| 説明は良いのに選択がおかしい | システムプロンプトのキーワード依存の指示を見直す |
| エージェントがむだに再試行する | 構造化エラー（種類、再試行できるか、説明） |
| 業務ルール違反のエラー | 再試行不可と、顧客向けの説明を返す |
| 検索結果が0件か、失敗か | 区別して返す。失敗を空の成功にしない |
| ツールが18個で選択が不安定 | 役割ごとに必要なものだけ |
| 統合エージェントの往復が多い | 範囲を絞った verify_fact。複雑なものはコーディネーター経由 |
| 必ずツールを呼ばせる / 特定のツールを最初に | "any" / {"type": "tool", "name": ...}（新しいモデルでは auto + strict などに置き換え） |
| チームで共有する MCP / 個人の MCP | .mcp.json / ~/.claude.json |
| トークンをコミットしない | ${GITHUB_TOKEN} の環境変数展開 |
| Jira と連携 | 既存の MCP サーバー |
| 探索の呼び出しを減らす | MCP リソースで一覧を見せる |
| 中身を検索 / ファイル名で探す | Grep / Glob |
| Edit が一意に一致しない | Read して Write |
7. 用語集
| 用語 | 意味 |
|---|---|
| ツールの境界 | そのツールを使う場面と使わない場面の線引き |
isError |
MCP のツール結果で、実行が失敗したことを示す印 |
| 一時的エラー | 時間をおけば成功しうるエラー（タイムアウトなど） |
| 横断ツール | 役割の違うエージェントにも、特定の用途だけ渡すツール |
| 環境変数展開 | 設定ファイルの ${VAR} を、実行時に環境変数の値で置き換えること |
| MCP リソース | MCP サーバーがアプリに渡す、読み取り専用のデータ |
出典
- Claude Certified Architect – Foundations Exam Guide（PDF、Version 1.0、2026年7月）: 第6章 ドメイン2、第9章のサンプル問題
- Define tools（Claude Platform Docs）: 説明文のベストプラクティス、
tool_choice、強制が使えないモデルと設定 - Writing effective tools for agents（Anthropic Engineering）: 目的に合ったツール、名前の付け方、役に立つエラー
- MCP Specification: Tools（modelcontextprotocol.io）: プロトコルのエラーとツール実行のエラー（
isError） - Connect Claude Code to tools via MCP（Claude Code Docs）: スコープ（local / project / user）、
.mcp.json、環境変数展開、リソースの@参照 - How the agent loop works（Claude Code Docs）: 組み込みツールの一覧
注意: MCP の仕様は Anthropic が始めたオープンな仕様で、modelcontextprotocol.io で公開されています。errorCategory や isRetryable の名前は試験ガイドの例で、標準の項目ではありません。内容は2026年11月時点のもので、上の出典を要約・言い換えたものです（ライセンスに配慮して書き直しています）。