エージェント向けツール設計の原則 — Anthropicが説く5つの設計指針と評価駆動の作り方

エージェントの実力は、与えるツールの設計に強く縛られます。Anthropicのengineeringブログ「Writing effective tools for agents — with agents」(2025年9月11日公開、Ken Aizawa氏ほか)は、その制約を真正面から扱った記事です。本稿では、Anthropic自身が内部のSlack / Asanaツールで実証した知見を、5つの設計原則と評価ループに分けて整理し、MCPやAgent SDKでツールを書く人が今日から使える観点に翻訳していきます。

背景 — 「決定的システムと非決定的エージェントの新しい契約」

記事の核となるフレームは、ツールを 「決定的(deterministic)なシステム」と「非決定的(non-deterministic)なエージェント」とのあいだの新しい契約形態 として捉え直すという主張です。原文は "Tools are a new kind of software which reflects a contract between deterministic systems and non-deterministic agents." と表現しています。

従来のAPI / SDKは、人間のプログラマがドキュメントを読んで使う前提で設計されてきました。一方、LLMエージェントが呼び出すツールは、「呼ぶ側が確率的に振る舞う」「文脈ウィンドウに収まる範囲でしか情報を保持できない」という固有の制約のもとで動きます。Anthropicが強調するのは、既存APIをそのままラップしてツール化するだけでは、この前提のずれを埋められないという点です。

背景には、MCP(Model Context Protocol)とAgent SDKの普及で 「とりあえずツールを生やせるようになった」段階を超え、品質が問題になってきた 現状があります。記事冒頭の "Agents are only as effective as the tools we give them." という一文は、その問題提起を端的に示しています。

ツール設計の5原則 — Anthropicが整理する観点

記事はツール設計の指針を5つに整理しています。それぞれの要点と実務上の翻訳を順番に見ていきます。

原則1：何を実装し、何を実装しないかを選ぶ

最初の原則は、ツール選定そのものです。Anthropicは 「より多くのツールが必ずしも良い結果につながらない」 と明言しています。エージェントは文脈ウィンドウに制限があり、ツールが多すぎると選択コストとトークン消費が増えていきます。

記事が挙げる具体例は、住所録検索の対比です。全連絡先を返すlist_contactsは文脈を浪費する一方、search_contactsは関連分だけを返せるため効率的です。同様に、list_users + list_events + create_eventのような細粒度の組み合わせは、schedule_event(可用性検索を内包)のような タスク単位のツール に集約したほうがエージェントの認知負荷が下がります。

実務観点での翻訳としては、「人間プログラマ向けのCRUD APIをそのまま生やさない」 が重要です。MCP server / Agent SDKでツールを書くときは、エージェントが解きたいタスクの粒度に合わせて再設計する余地が残っています。

原則2：ネームスペースで境界を可視化する

2つ目はネームスペース化です。ツール名にプレフィックス / サフィックスを付け、機能境界を明示する設計が推奨されています。

記事は2つの粒度を例示しています:

• サービス別: asana_search と jira_search のようにサービス名を頭に付ける
• リソース別: asana_projects_search と asana_users_search のようにリソース名を組み合わせる

興味深いのは、「効果はモデル依存である」 と但し書きが付いている点です。命名規約はLLMの振る舞いに直接効きますが、最適解は単一ではないため、自分のユースケースで評価して決める姿勢が求められます。複数MCPサーバーを並べる構成では、サーバー名と関数名の組合せでフルパスが長くなりすぎないよう、命名コストとのバランスも見る必要があります。

原則3：レスポンスに「意味のある文脈」を返す

3つ目はレスポンス設計です。Anthropicは 低レベルの技術識別子(uuid / 256px_image_url 等)よりも、name / image_url / file_type のような意味のあるフィールドを優先する ことを推奨しています。エージェントは返ってきた文字列を読んで次の行動を決めるため、IDだけでは判断できないというのが理由です。

加えて、response_formatパラメータでエージェントに "detailed" / "concise" を選ばせる工夫が紹介されています。記事内の比較例では、

• detailed応答: 約206トークン
• concise応答: 約72トークン

と、約3分の1までトークンを削減できたとされています。原文も "we use ~⅓ of the tokens with \"concise\" tool responses" と明記しており、同じツールを呼んでも返却の粒度を切り替えられる設計 が文脈節約に効くことを示した実例です。

レスポンスのフォーマット(XML / JSON / Markdown)は、LLMの訓練データとの相性で性能が変わるとも触れられています。ここも「自分の評価で決める」観点が繰り返されています。

原則4：トークン効率を構造で担保する

4つ目はトークン効率です。Claude Codeでは デフォルトで25,000トークンの上限 をツールレスポンスに設けていることが具体的に示されています。これを超えそうな場合、ツール側であらかじめ次の仕組みを用意しておく構成が推奨されます:

• ページング: page / cursorで分割
• 範囲選択: 行範囲 / 日付範囲で絞る
• フィルタリング: 必要なフィールドだけ返す
• 打ち切り処理: 上限を超えたら明示的にtruncateして「次のクエリヒント」を添える

エラー応答も同じ思想で書きます。「不明瞭なエラーコード」ではなく、「次に何をすればよいか」を文章で示すフィードバック をエージェントに返すと、リトライ精度が上がるという指摘です。打ち切り応答であれば、「より小さく的を絞った検索を複数回行ってください」のような具体指示を入れる例が挙げられています。

原則5：説明文をプロンプトとして書く

5つ目はツール説明(description)とスキーマ(spec)のプロンプトエンジニアリングです。記事のメタファは「新入社員にツールを説明するように書く」です。暗黙の文脈(クエリ形式の癖、用語の意味、リソース間の関係)を明示するほど、エージェントの呼び出し品質が上がります。

具体的には次のような書き換えが挙げられています:

• パラメータ名を user ではなく user_id に(曖昧性の排除)
• 入出力の型と意味を厳密に定義する
• 期待値・制約・前提条件を冗長気味に書く

効果として、SWE-bench Verifiedにおいて、Claude Sonnet 3.5が「ツール説明の精密化」だけで当時の最先端性能に達したケースがあった ことが触れられています。コードを変えず、descriptionを丁寧に書き直すだけで挙動が変わる、というのはMCP serverを運用する人にとって重要な示唆です。

評価駆動の3段階プロセス — 「エージェントと一緒にツールを直す」

設計原則と並行して、記事はツールを継続改善する 3段階のループ を提案しています。

段階1：プロトタイプを早く立てる

Claude CodeとローカルMCPサーバーで素早く動かし、現場ユーザーから粗い部分のフィードバックを取ることが推奨されています。ここで重要なのは、最初から完成度を狙わず 「破綻ポイントを早期に晒す」 ことです。

段階2：評価をプログラムで回す

評価タスクは「複数ツール呼び出しが必要な実世界タスク」を中心に組みます。記事が挙げる強い評価例 / 弱い評価例の対比が示唆的です:

評価実行は シンプルなwhileループのagentic loop をAPI呼び出しで回す形が紹介されています。Claudeを使う場合はinterleaved thinking(中間推論の差し挟み)も活用できると述べられています。記録すべきメトリクスは次の5つです。

段階3：エージェントに直させる

最後の段階で、Anthropicは Claude Code自身に評価トランスクリプトを読ませて、ツール実装の矛盾を直させる ループを紹介しています。記事内の図で示されたheld-out test setでの内部Slack / Asanaツールの比較では、人間が手で書いたツールよりClaudeに最適化させたツールのほうが性能が伸びた ことが報告されています(具体的な改善率は数値ではなくグラフで提示)。

これは「AIにツールを書かせる」というより、失敗ログをLLMに読ませて改善案を出させる、という評価駆動のループそのものをツール設計に組み込む という発想です。Anthropic内部の実例として再現性のあるアプローチとして示されています。

既存APIをそのままMCPツール化する設計が抱えるリスク

ここからは記事の主張を踏まえた編集視点です。今ある社内APIをMCP serverとして「とりあえず生やす」設計は、運用後に次の3点で詰まりやすいと整理できます。

1. 粒度のミスマッチ：CRUDをそのまま並べるとエージェントが何度も連続呼び出しを行い、文脈と時間を浪費する。Anthropicのschedule_eventの例は「タスク単位への集約」で解決している
2. レスポンスの肥大：API設計時点では想定していなかった全フィールド返却が、エージェントの文脈を圧迫する。response_formatのような濃淡切り替えがないと25,000トークン上限に引っかかる
3. descriptionの薄さ：OpenAPIから自動生成したdescriptionは人間向けで、エージェントが必要とする「いつ呼ぶか」「何と組み合わせるか」が抜けがち

Claude Code完全ガイド2026で扱っているように、Skills / Sub-agents / MCPの3層構造で拡張するときも、最下層のMCPツールがこの3点で詰まると、上位のSkillsやSub-agentsの設計でカバーするのは難しくなります。「ツール側で解決すべきものをプロンプト側で吸収する」 状態は、運用が進むほど技術的負債になりやすい構造です。

ツール品質改善の優先順位 — 何から手を付けるか

記事の5原則は等価に並んでいますが、実装フェーズによって投資対効果が変わります。編集視点で並べると次の通りです。

特に 原則5(description)はコードを触らずに改善できる 点で、運用中のMCPサーバーに後付けしやすい施策です。SWE-bench Verifiedの例が示すように、descriptionの精度がエージェント性能を底上げする余地は思ったより大きいと考えられます。

評価駆動ループをチームに定着させる現実的な道筋

3段階プロセスは原理的には正しい一方、社内に定着させるには次のような中間ステップが要りそうです。

• トランスクリプト保管の仕組み: agentic loopの呼び出し履歴をログとして残す。後段で「Claudeに読ませて改善させる」ステップが成立する前提条件
• 評価データセットの内製: 記事は「実世界タスクをベンチマーク化せよ」と促していますが、これは1日では作れない資産。チームの実運用ログから抽出するルートが現実的
• メトリクスのダッシュボード化: 5つのメトリクスを単発で測るのではなく、ツールごとに継続観測する基盤(Prometheus / 内製DBなど)が要る
• 「ツールリファクタ」を継続作業に位置付ける: 機能追加だけでなく、既存ツールのdescription / レスポンス整理を定期タスクに組み込む

Claude CodeのCLAUDE.md実用パターンで扱った「プロジェクト固有の運用知をmdに集約する」発想とも近く、ツール側のdescriptionをプロジェクト規約とセットで育てる構図が見えてきます。

まとめ

Anthropicの記事「Writing effective tools for agents」が示しているのは、ツール設計を「ソフトウェアの一機能」から「決定的システムと非決定的エージェントの契約」に再定義する という視点の転換です。具体的には次の5点に翻訳できます。

1. 何をツール化するかをタスク粒度で選ぶ(細粒度API的な発想を捨てる)
2. ネームスペースで境界を可視化する(ただし最適解は評価で決める)
3. レスポンスは意味あるフィールドで、濃淡切り替えで返す
4. トークン効率はツール側の構造で担保する(ページング / フィルタ / truncation)
5. descriptionは新入社員に説明するつもりで書く(コード変更なしで効く施策)

そして、この5つを支えるのが 「プロトタイプ → プログラム評価 → エージェントに直させる」 の3段階ループです。Anthropic内部のSlack / Asanaツールでは、人間設計よりClaude最適化版のほうが性能が伸びたという実証もあります。

MCPサーバーやAgent SDKでツールを書いている人にとって、まず効きそうなのは 原則5(descriptionの書き換え) と 原則3(レスポンスの濃淡切り替え) の2点です。コード変更が小さく、文脈効率に直接効くためです。実装の足回りはAgent SDK入門とMCP実用ガイドを併読してみてください。