マルチエージェントAgent SDK のツール検索｜道具が多くても迷わない
この記事の要点
- ツール検索は、道具の説明を最初に全部読ませず、必要になった時に探して読み込む仕組み。既定でオン
- 道具が多いほど効果が大きい。10個くらいまでなら、最初から全部読み込む方が速いこともある
- 見つけてもらえるかは、道具の名前と説明の書き方で決まる
AI エージェントに社内のシステムを次々つないでいくと、「道具が増えたら、選び間違いが増えた」「本題の作業に使える余白が減った」 ということが起きます。道具の説明そのものが、AI が一度に覚えておける量（コンテキスト）を使ってしまうためです。
この記事では、公式ドキュメント「Scale to many tools with tool search」（2026年11月11日確認）にもとづいて、Claude Agent SDK のツール検索の仕組みと設定を整理します。外部の道具をつなぐ方法は Agent SDK で MCP サーバーをつなぐ で解説しています。
結論：道具の説明は「必要になった時だけ」読み込む
ツール検索がオンの時、道具の説明は最初から AI に渡されません。 AI には使える道具のあらましだけが伝わり、まだ読み込んでいない力が必要になった時に、道具の一覧を探して、関係のありそうなものを読み込みます。
公式ドキュメントでは、道具が増えた時の2つの問題が挙げられています。
| 問題 | 中身 |
|---|---|
| 余白が減る | 道具50個の説明で、1万〜2万トークンを使うことがある |
| 選び間違い | 一度に30〜50個を超えて読み込むと、選ぶ正確さが落ちる |
ツール検索は既定でオン です。特別な設定をしなくても、多くの場合はこの動きになります。
探すたびに1往復増える
1回探すと、関係の深い道具が既定で最大5つ 読み込まれ、その後の会話でも使える状態で残ります。ただし、探すたびにやりとりが1往復増えます。
道具の数が10個くらいまでで、説明が余白に十分収まるなら、最初から全部読み込む方が速いことが多い とされています。道具が多いほど、ツール検索の得が大きくなります。
ENABLE_TOOL_SEARCH の5つの値
ツール検索の動きは、環境変数 ENABLE_TOOL_SEARCH で決めます。
| 値 | 動き |
|---|---|
| 指定しない | オン。必要な時に探して読み込む |
| true | オン（指定しない時と同じ） |
| auto | 最初は全部読み込み、道具の説明が余白の10%に達したらオンになる |
| auto:N | auto と同じで、オンになる割合を N% に変える（例 auto:5 なら5%） |
| false | オフ。毎回すべての説明を読み込む |
値は、query() の env オプションに入れます。TypeScript 版では env を指定すると元の環境変数が置き換わる ので、元の値も一緒に入れます。Python 版では、元の環境変数の上に足されます。
設定してもオンにならない場合
次の場合は、ENABLE_TOOL_SEARCH を何にしても、最初から全部読み込む動きになります。
- SDK が対応していないモデル：Opus 4・Sonnet 4・Haiku 4.5 より前のモデル
- Google Cloud の Agent Platform の古いモデル：Opus 4.5・Sonnet 4.5・Haiku 4.5 より前のモデル
- Microsoft Foundry の Azure 上の環境：サーバー側で断られるため、SDK が自動で全部読み込みに切り替える
- 試験的な機能をまとめて止める設定を入れている時：CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS を入れると、ツール検索もオフのまま
社内の中継（ゲートウェイ）を通している場合も、既定でオン です。中継側で断られる時の対処は、公式ドキュメントの MCP のページにまとめられています。
見つけてもらいやすい道具の書き方
探す時に照らし合わせるのは、道具の名前と説明です。 書き方で、見つかりやすさが変わります。
- 名前は中身が分かる形に：「query_slack」より「search_slack_messages」の方が、いろいろな頼み方で見つかる
- 説明には具体的な言葉を：「Slack を調べる」より「キーワード・チャンネル・日付で Slack のメッセージを探す」の方が当たる
- 道具の種類をシステムプロンプトに書く：どんな種類の道具があるかを書き足しておくと、AI が何を探せばよいか分かる
システムプロンプトに書き足す時は、既定の内容を置き換えず、後ろに足す形（append） を使います。書き足し方は Agent SDK のシステムプロンプト で解説しています。
上限
| 項目 | 上限 |
|---|---|
| 道具の数 | 一覧に登録できるのは10,000個まで |
| 1回で読み込む数 | 既定で最大5つ |
よくある質問
自分で作った道具にも効きますか？
効きます。 外部の MCP サーバーの道具にも、SDK の中で作った道具にも同じように効きます。auto を使う時は、読み込みを後回しにできる道具の説明をすべて合わせた量で、割合を判断します。自分で道具を作る方法は Agent SDK でカスタムツールを作る で解説しています。
道具が少ないのにオンのままで大丈夫ですか？
動きはしますが、探す1往復のぶん遅くなることがあります。 道具が少なく速さを優先したい時は、false で最初から全部読み込む方法もあります。余白の使い方は Claude Code のコンテキストウィンドウ でも解説しています。
まとめ
- ツール検索は 道具の説明を必要な時だけ読み込む 仕組みで、既定でオン
- 道具が多いほど得が大きい。10個くらいまでなら全部読み込む方が速いこともある
- 見つかりやすさは 道具の名前と説明の書き方 で決まる
出典
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。
