AIエージェントのツール設計7原則 — 実運用で学んだ勘所

AIエージェントを本番で使い始めると、最初にぶつかるのが「ツールの設計」です。

自分はClaude Codeを日常的に使って開発・運用をしていますが、ツールの定義を雑に書くと、エージェントが見当違いのツールを選んだり、パラメータを間違えたりする場面に何度も遭遇しました。AnthropicとOpenAIがそれぞれ公式ガイドでツール設計の原則を示していますが、これらは机上の理論ではなく、実運用で痛い目を見た人には「そうそう、これ」と頷けるものばかりです。

この記事では、両社のガイドから抽出された7つの設計原則を、自分の実体験を交えて整理します。

1. 単一責任 — 「何でもできるツール」は何もできない

1つのツールは1つの明確な操作だけを担うべきです。

たとえば「ファイルを検索して内容を読んで編集する」を1つのツールにまとめると、LLMはどの場面でそのツールを使うべきか迷います。検索・読み取り・編集をそれぞれ独立したツールにすることで、エージェントの選択精度が上がります。

自分のClaude Code設定でも、以前は汎用的な「プロジェクト操作」ツールを作ろうとして失敗しました。結局、Glob（ファイル検索）、Read（読み取り）、Edit（編集）というシンプルな分割が最も安定します。Anthropicはこれを「God Tool」問題と呼んでいて、万能ツールがLLMの選択精度を低下させることを明確に警告しています。

2. 冪等性 — リトライしても壊れない設計

エージェントは失敗するとリトライします。これは避けられません。

問題は、リトライ時に副作用が重複することです。たとえば決済処理ツールがリトライで二重課金を起こしたら致命的です。idempotency_key パターンで、同じリクエストが複数回実行されても結果が変わらないように設計する必要があります。

実際の開発でも、Slack投稿やファイル書き込みなど副作用のあるツールには、「すでに実行済みかどうか」のチェックを入れるようにしています。Claude Codeのサブエージェントがタイムアウトで再実行されることは珍しくないので、この設計は保険ではなく必須です。

3. セマンティック明確性 — docstringはLLMへの指示書

ここが最も見落とされがちで、最もインパクトが大きいポイントです。

ツールのdocstring（説明文）は人間の開発者向けのドキュメントではなく、LLMが「いつこのツールを使うべきか」を判断するための指示書です。Anthropicのガイドでは、USE THIS TOOL WHEN... / DO NOT USE THIS TOOL WHEN... を明記し、パラメータのフォーマットを具体例で示すことを推奨しています。

ある検証では、この書き方を徹底しただけでパラメータの正確性が72%から90%に向上したという報告があります。自分も .claude/rules/ にツールの使い分けルールを書いていますが、曖昧な説明と具体的な説明では、エージェントの挙動が明らかに変わります。

4. スキーマ制約 — 構造で選択肢を絞る

LLMの出力を自由形式で受け取ると、予期しない値が紛れ込むリスクがあります。

OpenAIのstrict modeでは、enum制約やadditionalProperties: falseを使って、LLMが出力できる値を構造的に制限します。「東京」「大阪」「名古屋」しか選べないパラメータなら、enumで定義すれば幻覚的な値が入る余地がなくなります。

Claude Codeの文脈では、Tool Useのinput_schemaを厳密に定義することが同じ効果を持ちます。型安全なスキーマ定義は、TypeScriptの型システムと同じ発想です。コンパイル時（＝ツール呼び出し時）にエラーを防ぐほうが、ランタイム（＝実行結果の検証）で防ぐより遥かに効率的です。

5. エラー防止設計（Poka-yoke） — 間違えられない仕組みを作る

トヨタ生産方式の「ポカヨケ」と同じ発想を、ツール設計に適用します。

具体例: ファイルパスを受け取るツールで、相対パスを受け付けると実行環境によって結果が変わります。絶対パスのみを受け付ける設計にすれば、この問題は構造的に発生しません。

自分のClaude Code運用では、エラーメッセージに「次に何をすべきか」を含めるようにしています。たとえば「ファイルが見つかりません」ではなく「ファイルが見つかりません。Globツールでファイル名を検索してください」と返す。エージェントは次のアクションが明示されていると、リカバリの精度が格段に上がります。

6. コンポーザビリティ — ツール同士が自然に繋がる

小さなツールの出力が、別のツールの入力としてそのまま使える構造にします。

Unixの哲学と同じです。grep の出力を wc -l にパイプできるように、あるツールが返すファイルパスのリストを、次のツールがそのまま受け取れる設計が理想です。

AIエージェントの文脈では、ツールAの返り値のスキーマとツールBの入力スキーマの互換性を意識することが大切です。独自のデータ構造を返すツールは、後続のツールと接続するために変換レイヤーが必要になり、エラーの温床になります。

7. セキュリティ多層防御 — 信頼しつつ検証する

AIエージェントに権限を与える以上、セキュリティは避けて通れません。

Anthropicのガイドでは、入力検証・権限制御・実行制限の3層防御を推奨しています。特に破壊的操作（ファイル削除、本番デプロイなど）には「ブラスト半径制限」と「人間承認フロー」が必須です。

自分のClaude Code設定では、settings.json の権限設定で破壊的なBashコマンドを制限し、worktreeで分離実行することでブラスト半径を限定しています。最近話題になった「Claude Codeで1日PR8本」の事例でも、リスクベースの分類（高リスク→スキップ通知、中リスク→worktree+diffレビュー、低リスク→完全自動化）が成功の鍵でした。

2026年の最新パターン: ツール数の爆発にどう対処するか

原則を守ってツールを細かく分割すると、今度はツール数が爆発するという問題が起きます。

ここで登場するのが Tool Search Tool という概念です。常時ロードするツールを3-5個に絞り、残りは必要なときにだけ遅延ロードする。Anthropicの実装では、これによりコンテキスト消費を85%削減できたと報告されています。

Claude Codeでもまさにこの仕組みが使われています。基本ツール（Read, Edit, Bash, Grep, Glob）は常時利用可能で、MCPサーバー経由の専門ツールは必要に応じてロードされます。ツール設計が成熟するほど、「どのツールをいつ見せるか」というメタレベルの設計が重要になります。

まとめ: ツール設計はプロンプトエンジニアリングより重要

Anthropicが「プロンプト設計以上に重要」と述べているのは誇張ではありません。

プロンプトはセッションごとに調整できますが、ツール設計はシステムの基盤です。冪等性のないツールは何度プロンプトを調整しても二重実行のリスクが消えないし、セマンティクスが曖昧なツールはどんな精緻な指示を書いても選択ミスが起きます。

AIエージェントを「動く」から「信頼して任せられる」に進化させるための第一歩は、ツール設計を見直すことだと、自分は実感しています。

自分のツール設計で意識していることをまとめると、こうなります。

• 1ツール1責任 を徹底する（迷ったら分割）
• docstringに使用条件 を明記する（LLMが読むドキュメント）
• リトライ安全性 を前提に設計する（冪等性キー）
• エラーメッセージに次のアクション を含める（ポカヨケ）
• 破壊的操作は人間承認必須 にする（多層防御）

ツールの設計を見直すだけで、エージェントの挙動は驚くほど安定します。これからエージェント開発を始める方にも、すでに運用している方にも、この7原則は立ち返る価値のある指針です。