コンテンツにスキップ
mild worksai-tools-kb

Tool search（多数のツールへの拡張）

facts ／Claude Code ／agent-sdk-tool-search

stable1 か月前 · 2026-08-23

概要

ツール定義をあらかじめすべてコンテキストへ読み込む代わりに、エージェントがツールカタログを検索し、必要なものだけをその場で読み込む仕組み。数百〜数千のツールを扱うために使う。

解決する問題は 2 つ。

  • コンテキストの効率: ツール定義はコンテキストウィンドウを大きく食う（50 個で 10〜20K トークン）
  • ツール選択の精度: 一度に 30〜50 個を超えて読み込むと選択の精度が落ちる

仕様

動作

  • 既定で有効（下記の例外を除く）
  • 有効なとき、ツール定義はコンテキストウィンドウに載らない。エージェントは利用可能なツールの要約を受け取り、読み込み済みのツールに無い能力が必要になった時点で検索する
  • 既定では、関連度の高い最大 5 件がコンテキストへ読み込まれ、以降のターンでも使える状態で残る
  • 会話が長くなり SDK が以前のメッセージを compact して場所を空けた場合、発見済みのツールが外れることがあり、必要に応じて再検索する
  • Claude が初めてツールを発見するときだけ 1 往復（検索の手順）が増える。大きなツール集合ではターンごとのコンテキスト縮小がこれを上回る。定義がコンテキストに収まる 10 個未満の場合は、最初にすべて読み込むほうが速いのが普通

適用範囲

  • 登録されたすべてのツールに適用される。リモートの MCP サーバー由来でも、custom SDK MCP サーバー由来でも同じ
  • auto を使う場合、遅延可能な定義をすべて 1 つの閾値に合算する。alwaysLoad の付いていない MCP ツール（サーバーを問わず）と、オンデマンドで読み込まれる組み込みツールが対象
  • Bash・Read・Edit のような中核の組み込みツールは常に最初に読み込まれ、閾値に数えない

ANTHROPIC_BASE_URL が first-party でないホストを指す場合、SDK は tool search を無効にする（多くのプロキシが tool_reference ブロックを転送しないため）。この既定は環境変数で上書きできる。

値挙動
（未設定）有効。定義は遅延され、必要時に発見される。Google Cloud's Agent Platform の Claude 4.5 世代より前のモデル、first-party でない ANTHROPIC_BASE_URL、Azure でホストされる Microsoft Foundry のデプロイでは、最初にすべて読み込む動作へ落ちる
true常に有効。ただし Azure でホストされる Microsoft Foundry のデプロイではサーバー側の拒否により最初の読み込みが強制され、Agent Platform の Claude 4.5 世代より前のモデルでも最初の読み込みのままになる。SDK はプロキシへ beta header を送るため、tool_reference ブロックに対応しないプロキシではリクエストが失敗する
autotool search が遅延できるツール定義のトークン数を数え、モデルのコンテキストウィンドウと比較する。合計がウィンドウの 10% に達した時点で有効化する。それ未満ならすべて最初に読み込む
auto:Nauto の割合を変える。auto:5 は 5% で有効化する。値が小さいほど早く有効になる
false無効。毎ターン、すべてのツール定義をコンテキストへ読み込む
  • 設定は query() の env オプションで渡す。TypeScript では env がサブプロセスの環境を置き換えるため、継承した変数を保つには ...process.env を展開する。Python では継承した環境の上にマージされる
  • CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS を設定すると tool search は無効のままになる。ENABLE_TOOL_SEARCH で上書きできない。組織は managed settings で有効のままにできる（Claude Code v2.1.227 以降）

モデルと環境による違い

  • SDK が持つ非対応モデルの一覧に載っているモデルでは、ENABLE_TOOL_SEARCH の値に関わらず最初にすべて読み込む
  • Google Cloud's Agent Platform ではモデル世代で決まる
    • Claude Opus 4.5 / Sonnet 4.5 / Haiku 4.5 以降: 既定で有効
    • それより前のモデル: 必要な beta header を配信スタックが拒否するため、最初にすべて読み込む（ENABLE_TOOL_SEARCH で上書きできない）
  • Claude Code v2.1.221 より前は、ENABLE_TOOL_SEARCH を設定しない限り Agent Platform の全モデルで無効だった

検索されやすくする

  • 検索はツール名と説明文に対して照合される
  • query_slack より search_slack_messages のような名前のほうが、広い範囲の要求で表に出る
  • 「Query Slack」のような一般的な説明より、「Search Slack messages by keyword, channel, or date range」のように具体的な語を含む説明のほうが多くの問い合わせに一致する
  • システムプロンプトに利用できるツールの分類を列挙する節を足すと、どんなツールを検索できるかの文脈を与えられる。TypeScript の systemPrompt / Python の system_prompt で、claude_code preset の append を使う（preset のプロンプトを置き換えずに追記する）

設定

options: {
  mcpServers: {
    "enterprise-tools": { type: "http", url: "https://tools.example.com/mcp" }
  },
  allowedTools: ["mcp__enterprise-tools__*"],
  env: {
    ...process.env,
    ENABLE_TOOL_SEARCH: "auto:5"
  }
}

制約・注意点

  • ツールカタログの上限は 10,000 件
  • 1 回の検索で返るのは既定で最大 5 件（関連度順）
  • 対応モデルは Claude Sonnet 4.5 / Haiku 4.5 / Opus 4.5 以降。 同じ下限が Google Cloud's Agent Platform にも適用される
  • Azure でホストされる Microsoft Foundry のデプロイでは非対応。サーバー側が拒否し、SDK はそれを検出して、そのデプロイでは最初にツール定義を読み込む。拒否はデプロイ側から来るため ENABLE_TOOL_SEARCH で上書きできない

関連

  • facts/claude-code/agent-sdk.md
  • facts/claude-code/agent-sdk-custom-tools.md
  • facts/claude-code/mcp.md
  • facts/claude-code/env-vars.md