Agent SDK Tool Searchの使い方 — 数千ツールをオンデマンド発見
Agent SDKのTool Searchで数百〜数千のツールをオンデマンド読み込みする設定方法。ENABLE_TOOL_SEARCHの値ごとの挙動と、検索精度を上げるコツをまとめます。
Agent SDK Tool Searchとは — ツール定義を「必要になってから」読み込む仕組み
Agent SDK Tool Searchとは、数百から数千のツールをカタログとして持たせつつ、実際にはその場のタスクに必要な分だけをオンデマンドで読み込ませる機能です。ツール定義は50個で1〜2万トークンを消費し、30〜50個を超えたあたりからツール選択の精度そのものが落ち始めます。Tool Searchはこの2つの問題を、定義そのものをコンテキストから外すことで同時に解消します。
有効になっている間、Claudeにはツール名の一覧(要約)だけが見え、タスクに関連しそうなツールが必要になった時点で検索を行い、既定では最も関連度の高い5件までを読み込みます。読み込まれたツールはその後のターンでも使えますが、SDKがメッセージを圧縮したタイミングでコンテキストから外れ、次に必要になったときは再び検索し直します。検索のたびに1往復分のやり取りが増えますが、ツール数が多い構成では毎ターンのコンテキスト削減分がそれを上回ります。10個未満で全部の定義がコンテキストに収まる規模なら、最初から全部読み込ませたほうが速いのが実情です。
MCPサーバー経由のツールも、インプロセスのSDKカスタムツールも、どちらもTool Searchの対象です。組み込みのBash / Read / Editのような中核ツールは常にコンテキストへ先読みされ、しきい値の対象になりません。
手順1 — 既定動作を確認する
Tool Searchは既定でオンです。特別な設定をしなくても、ツール数が多い構成では自動的に働きます。ただし例外がいくつかあります。SDKが対応外と判定しているモデルでは、ENABLE_TOOL_SEARCH の値に関わらず全ツール定義が最初から読み込まれます。Microsoft FoundryのAzureホスト環境ではサーバー側がTool Searchのリクエストをそもそも拒否するため、SDKがその拒否を検知して事前読み込みに切り替えます。ANTHROPIC_BASE_URL が非公式プロキシを指しているときも既定でオフになります。プロキシの多くが tool_reference ブロックを転送しないためです。
手順2 — ENABLE_TOOL_SEARCHで挙動を上書きする
query() の env オプションに ENABLE_TOOL_SEARCH を渡すと、既定の判定を上書きできます。
| 値 | 挙動 |
|---|---|
| 未設定 | 挙動既定の判定に従う(通常オン。上記の例外条件でのみオフ) |
true | 挙動常にオン(Azureホストの拒否や旧世代モデルの制約は上書きできない) |
auto | 挙動遅延可能なツール定義の合計トークン数が、モデルのコンテキストウィンドウの10%に達したらオンにする |
auto:N | 挙動auto と同じ判定をN%のしきい値で行う。auto:5 なら5%到達で有効化 |
false | 挙動常にオフ。全ツール定義を毎ターン読み込む |
TypeScriptで env オプションを渡すときは、サブプロセスの環境変数がまるごと置き換わる点に注意してください。...process.env を展開しておかないと、継承していたはずの他の環境変数が消えます。Pythonでは逆に、渡した値が継承環境の上に重ねてマージされます。
options: {
mcpServers: { "enterprise-tools": { type: "http", url: "https://tools.example.com/mcp" } },
allowedTools: ["mcp__enterprise-tools__*"],
env: {
...process.env,
ENABLE_TOOL_SEARCH: "auto:5"
}
}CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS を設定すると、Tool Searchは強制的にオフのままになります。ENABLE_TOOL_SEARCH をどう設定してもこちらが優先されます。組織全体でオンを固定したい場合は、v2.1.227以降でmanaged settingsから制御できます。
手順3 — 検索精度を上げる
検索の仕組みはツール名と説明文をクエリと照合するだけなので、命名と説明文の質がヒット率を左右します。search_slack_messages のような具体的な名前は、query_slack のような抽象的な名前より幅広いリクエストにマッチします。説明文も「Slackを検索する」ではなく「キーワード・チャンネル・日付範囲でSlackメッセージを検索する」のように、検索されそうな語をあらかじめ含めておくと拾われやすくなります。
TypeScriptでは tool() の第5引数に searchHint を渡し、検索対象の一覧に出る一言説明を個別に調整できます。加えて、システムプロンプトに「どんな種類のツールを検索できるか」を書き添えておくと、Claudeが検索に踏み切る判断材料が増えます。
options: {
systemPrompt: {
type: "preset",
preset: "claude_code",
append: "You can search for tools to interact with Slack, GitHub, and Jira."
}
}環境ごとの対応状況
環境やモデル世代によって、Tool Searchが使えるかどうかとオーバーライドの効き方が変わります。
| 環境・モデル | 既定動作 | ENABLE_TOOL_SEARCH での上書き |
|---|---|---|
| Google CloudのAgent Platform、Opus 4.5 / Sonnet 4.5 / Haiku 4.5以降 | 既定動作オン | ENABLE_TOOL_SEARCH での上書き可能 |
| 同プラットフォームの旧世代モデル | 既定動作常に事前読み込み(サービング側がベータヘッダーを拒否) | ENABLE_TOOL_SEARCH での上書き不可 |
| Microsoft FoundryのAzureホスト | 既定動作常に事前読み込み(サーバー側が拒否) | ENABLE_TOOL_SEARCH での上書き不可 |
非公式の ANTHROPIC_BASE_URL | 既定動作既定オフ | ENABLE_TOOL_SEARCH での上書きtrue で上書き可能(プロキシが対応していれば) |
Google CloudのAgent Platformにおけるこの世代分岐は、Claude Code v2.1.221以降で入った挙動です。それより前のバージョンでは、ENABLE_TOOL_SEARCH を明示しない限り同プラットフォームの全モデルでTool Searchが無効化されていました。
カスタムツールと組み合わせるときの注意
SDKカスタムツールで作ったインプロセスサーバーのツールも、既定でTool Searchの遅延対象になります。頻繁に使う少数のツールだけは即時ロードのままにしておきたい場合、tool() の extras.alwaysLoad(TypeScript)か、createSdkMcpServer() の alwaysLoad オプションでサーバー単位に指定します。auto しきい値を使う場合、alwaysLoad を付けたツールの定義サイズはしきい値の計算対象から外れます。
MCPサーバーを何個も繋いでいる場合の考え方
複数のMCPサーバーを同時に設定していると、遅延可能なツール定義がサーバーをまたいで合算されます。auto を使うときにSDKが数えるのは、alwaysLoad を付けていないMCPツールすべて(どのサーバー由来かは問わない)と、オンデマンドで読み込まれるビルトインツールの合計です。5つのMCPサーバーで合計58個のツールを束ねるような構成では、個々のサーバーが小さくても合算のトークン数は無視できない規模になりがちです。Agent SDKからMCPサーバーに接続する手順で複数サーバーを繋ぐ設計をする際は、この合算の考え方を踏まえてしきい値を決めるとチューニングが的確になります。
制限値
ツールカタログの上限は1構成あたり10,000です。1回の検索で返るツールは既定で最大5件、モデル対応はSonnet 4.5・Haiku 4.5・Opus 4.5以降(Google CloudのAgent Platformも同じ下限)に限られます。この世代より前のモデルを指定した場合、SDKはTool Searchの有効化を試みず、常に全ツール定義を事前に読み込む経路へ静かに切り替えます。手元の構成が遅いと感じたら、まずモデル指定がこの対応表を満たしているかを確認する価値があります。
Tool Search ToolベータAPIとの違い
2025年11月にAnthropicが公開したAdvanced Tool UseのTool Search Toolは、Claude Developer Platform向けの生APIベータとして、ツールごとに defer_loading を明示的に付ける方式でした。当時の開示数値ではトークン使用量が85%削減、Opus 4のツール選択精度が49%から74%へ上がったと報告されています。
Agent SDKのTool Searchは、この仕組みをSDK側で既定オンに変え、defer_loading の個別指定を省いて ENABLE_TOOL_SEARCH 環境変数による一括制御に置き換えたものです。個々のツールに手を入れずに恩恵を受けられる代わりに、細かい単位でのオプトイン・オプトアウトはできません。数値の内訳や中間結果の扱いまで含めた広い文脈はAdvanced Tool Use側の記事、SDKでの具体的な設定方法は本記事、という役割分担になります。
早見表 — Tool Searchを切るべきかどうか
| 状況 | おすすめ | 理由 |
|---|---|---|
| 登録ツールが10個未満 | おすすめオフ(false) | 理由全部の定義がコンテキストに収まり、検索の往復コストが上回る |
| 数十〜数百のMCPツールを束ねている | おすすめオンのまま(既定) | 理由コンテキスト削減と精度向上の両方が効く帯域 |
| ツール数が変動する・複数の顧客ごとに構成が違う | おすすめauto か auto:N | 理由固定台数で判定せず、実際のトークン占有率で切り替えられる |
| AzureホストのMicrosoft Foundryを使っている | おすすめ設定不要 | 理由サーバー側が拒否するためSDKが自動的に事前読み込みへ切り替える |
よくあるつまずき
ENABLE_TOOL_SEARCHを設定したのに変わらない:CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASが設定されていないか確認してください。設定されていれば常にオフが優先されます。- TypeScriptで環境変数が消える:
envにオブジェクトを渡すとサブプロセスの環境がまるごと置き換わります。...process.envを先頭で展開しておかないと、他の環境変数まで巻き添えで消えます。 trueを指定したのにAzureで効かない: Microsoft FoundryのAzureホスト環境はサーバー側の拒否が優先されるため、ENABLE_TOOL_SEARCHの値では上書きできません。- 検索でツールが見つからない: ツール名や説明文が抽象的すぎる可能性があります。想定される検索語を説明文に具体的に含め、
searchHintを添えて調整します。
よくある質問
Tool Searchを使うと必ず速くなりますか
いいえ。ツール数が10個に満たず定義がコンテキストに余裕で収まる場合は、検索の往復が純粋なオーバーヘッドになり、全部読み込ませるより遅くなることがあります。
ビルトインツールにもTool Searchは効きますか
Bash・Read・Editのような中核ツールは常に事前読み込みされ、しきい値の計算対象にも含まれません。Tool Searchが対象にするのは、それ以外のオンデマンドで読み込まれるビルトインとMCP系のツールです。構成によっては、この対象範囲の違いを理解していないと「全部効くはず」という思い込みで挙動を誤解しやすい部分です。
組織全体で強制的にオンにできますか
v2.1.227以降のClaude Codeであれば、managed settingsから組織単位でTool Searchを固定できます。個々の開発者が環境変数で無効化することを防ぎたい場合に使います。
カタログの上限を超えるとどうなりますか
1構成あたり10,000ツールが上限です。それを超える規模のツールを扱いたい場合は、カタログ自体を用途別に分割し、必要なサーバーだけを実行時に接続する設計に見直す必要があります。プロジェクトやタスクの種類ごとにMCPサーバーの組み合わせを切り替える運用にしておくと、上限に張り付く事態を避けやすくなります。
まとめ
Agent SDK Tool Searchは、ツール数が増えるほど効果が出る仕組みで、既定でオンのまま使い始められます。台数が変動する構成では auto:N で実測ベースに切り替え、常用するツールだけ alwaysLoad で固定し、ヒット率が悪いと感じたらツール名と説明文を検索されやすい言葉に書き換えるのが実務上の調整の順番です。設定を変えたら、まず小さめのタスクで検索が正しいツールを拾えているかを確認してから、本番相当の構成に反映するのが安全です。