Agent SDK 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カスタムツールも、どちらも対象です。組み込みのBash / Read / Editのような中核ツールは常にコンテキストへ先読みされ、しきい値の数にも入りません。

動いていないときは、この順でオフの原因を探す

Tool Searchは既定でオンなので、設定を足さなくても大きな構成では自動で働きます。「効いていない」と感じたときは、設定値を触る前に、強制的にオフになる条件に当たっていないかを上から順に調べます。

Google CloudのAgent Platformでの世代による分岐は、Claude Code v2.1.221以降の挙動です。それより前のバージョンでは、ENABLE_TOOL_SEARCH を明示しない限り、同プラットフォームの全モデルでTool Searchが無効でした。

ENABLE_TOOL_SEARCHで挙動を上書きする

query() の env オプションに ENABLE_TOOL_SEARCH を渡すと、ここまでの条件に当たらない範囲で判定を変えられます。

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"
  }
}

組織全体でオンを固定したい場合は、managed settingsを使います。CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS が設定されていても、Tool Searchをオンに保てます(Claude Code v2.1.227以降、直接接続または ANTHROPIC_BASE_URL のゲートウェイ経由の場合)。クラウドプロバイダ経由やClaude apps gateway経由では効きません。Claude Codeの管理設定の一部です。

検索にヒットしないとき — 名前・説明文・システムプロンプトを直す

検索はツール名と説明文をクエリと照合して行われるため、命名と説明文の質がヒット率を左右します。search_slack_messages のような具体的な名前は、query_slack のような抽象的な名前より幅広いリクエストにマッチします。説明文も「Slackを検索する」ではなく「キーワード・チャンネル・日付範囲でSlackメッセージを検索する」のように、検索されそうな語を含めておくと拾われやすくなります。

自作のSDKツールなら、TypeScriptの tool() の第5引数 extras に searchHint を渡せます。searchHint は、Tool Searchが有効なときに遅延ツールの一覧へ出る一行の機能説明です。名前と説明文を変えずに検索の手がかりだけ足したいときに向いています。

const searchSlack = tool(
  "search_slack_messages",
  "キーワード・チャンネル・日付範囲でSlackメッセージを検索する",
  { query: z.string() },
  async ({ query }) => ({ content: [{ type: "text", text: `検索語: ${query}` }] }),
  { searchHint: "Slackのメッセージ検索" }
);

加えて、システムプロンプトに「どんな種類のツールを検索できるか」を書き添えておくと、Claudeが検索に踏み切る判断材料が増えます。claude_code プリセットの append を使うと、プリセットの内容を置き換えずに追記できます。

options: {
  systemPrompt: {
    type: "preset",
    preset: "claude_code",
    append: "You can search for tools to interact with Slack, GitHub, and Jira."
  }
}

常用するツールだけを先読みに固定する

頻繁に使う少数のツールは、検索の往復を挟まず最初から見えているほうが速く確実です。そのための alwaysLoad は、指定する場所によって効く範囲が違います。

auto のしきい値を使っているときは、alwaysLoad を付けたツールの定義サイズが計算から外れます。先読みにしたツールは、Tool Searchで削ったはずの定義を毎ターン使う側に戻すことになります。固定するのは、本当に毎ターン使うものに絞ります。

もう一つの代償が起動時の待ちです。alwaysLoad: true のサーバーは、最初のプロンプトを組み立てる時点でツールが揃っている必要があるため、起動時にそのサーバーのツールを待ちます。待ちの上限は既定で5秒で、MCP_CONNECT_TIMEOUT_MS で調整できます。リモートサーバーで前回の接続時のツール一覧がキャッシュに残っていれば、接続せずにそこから供給されて待ちは発生しません。

最初のターンでMCPツールが見つからないとき

MCPサーバーの接続には時間がかかるので、最初のターンの時点でまだ接続中のサーバーがありえます。Tool Searchが有効かどうかで、SDKの待ち方が変わります。

Tool Searchが有効なときは、接続待ちの対象は alwaysLoad: true を付けたサーバーだけです。残りのサーバーはバックグラウンドで接続を続け、接続が完了すると、Claudeの次のリクエストの時点でそのサーバーのツール名が一覧に加わります。Claudeは同じターンのうちに、それらを検索して呼び出せます。未接続のサーバーのツールが必要になった場合も、待ちは ToolSearch の呼び出しの中で起きます。

Tool Searchが無効なときは、最初のターンが接続中のサーバーすべてを待ちます。stdioサーバーや、ツール一覧のキャッシュがないHTTP / SSEサーバーの待ち上限は MCP_TIMEOUT で、既定は30秒です。接続中サーバーのツールをClaudeが必要としたときは、ToolSearch の代わりに WaitForMcpServers ツールが使われます。ENABLE_TOOL_SEARCH=false、公式以外の ANTHROPIC_BASE_URL、Agent Platformの旧世代モデルは、この無効側の構成にあたります。

待ち時間を自分で決めたいときは、env に CLAUDE_CODE_MCP_STARTUP_WAIT_MS をミリ秒で渡します。この値は、Tool Searchの有無にかかわらず、接続中のサーバーすべてを待つ上限として働きます。0 を渡すと待たずに始まります。Claude Code v2.1.274以降で使えます。

env: {
  ...process.env,
  CLAUDE_CODE_MCP_STARTUP_WAIT_MS: "5000"
}

遅いサーバーが1つあるだけで最初のターンが数十秒止まる構成なら、このミリ秒指定で上限を縮められます。そのぶん、間に合わなかったサーバーのツールは最初のターンでは使えません。使えるようになるのは接続が完了してからです。

.mcp.json やプラグインから読み込んだサーバーは、options.mcpServers が空かSDKサーバーだけなら、最初のターンで最大2秒だけ待たれます。permissionPromptToolName を設定していると、そのツールのサーバーを MCP_TIMEOUT を上限に必ず待ちます。インプロセスのSDKサーバーは、接続とツール列挙が済むまで最初のターンが遅れます。最初のターンより前、起動の段階で止めたいときは MCP_CONNECTION_NONBLOCKING を 0 にします。起動を接続バッチの完了まで止められます(既定の上限は5秒で、MCP_CONNECT_TIMEOUT_MS で調整)。

MCPサーバーを何個も繋いでいる場合の考え方

複数のMCPサーバーを同時に設定していると、遅延できるツール定義がサーバーをまたいで合算されます。auto を使うときにSDKが数えるのは、alwaysLoad を付けていないMCPツールすべて(どのサーバー由来かは問わない)と、オンデマンドで読み込まれる組み込みツールの合計です。個々のサーバーが小さくても、数を繋ぐほど合算のトークン数は大きくなります。

プラグイン側にも注意点があります。プラグインに含まれるmodがツールを遅延対象にしたり先読みにしたりすると、その分だけ数える対象が変わります。しきい値を決めたあとでプラグインを足したときは、auto:N の効き方を見直す必要が出ます。

Agent SDKからMCPサーバーに接続する手順で複数サーバーを繋ぐ設計をするときは、この合算の数え方を踏まえて auto:N の値を決めると、チューニングが的確になります。

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側で既定オンにしたものです。個々のツールに手を入れずに使えます。全体のオフは ENABLE_TOOL_SEARCH=false、例外として先読みにしたいものは alwaysLoad で指定します。

制限値

ツールカタログの上限は1構成あたり10,000です。1回の検索で返るツールは既定で最大5件です。モデルはSonnet 4.5・Haiku 4.5・Opus 4.5以降が対象で、Google CloudのAgent Platformも同じ下限です。

Tool Searchを切るかどうかの早見表

まとめ

効いていないと感じたら、ENABLE_TOOL_SEARCH の値を触る前に、強制オフの条件を上から潰すところから始めます。オンになっているのに拾われないツールだけが、名前・説明文・searchHint の調整対象です。