Skip to main content
ツール検索により、エージェントは数百または数千のツールを動的に検出し、オンデマンドで読み込むことで、それらと連携できます。すべてのツール定義をコンテキストウィンドウに事前に読み込む代わりに、エージェントはツールカタログを検索し、必要なツールのみを読み込みます。 このアプローチは、ツールライブラリがスケーリングするにつれて、2 つの課題を解決します。
  • コンテキスト効率: ツール定義はコンテキストウィンドウの大部分を消費する可能性があります(50 個のツールは 10~20K トークンを使用できます)。実際の作業用のスペースが減少します。
  • ツール選択精度: 30~50 個以上のツールが一度に読み込まれると、ツール選択精度が低下します。

ツール検索の仕組み

ツール検索はデフォルトでオンになっており、ツール検索の設定に記載されている例外があります。 ツール検索がアクティブな場合、ツール定義はコンテキストウィンドウから保留されます。エージェントは利用可能なツールの概要を受け取り、タスクが既に読み込まれていない機能を必要とする場合、関連するツールを検索します。最も関連性の高い 5 個までのツールがデフォルトでコンテキストに読み込まれ、その後のターンで利用可能なままになります。SDK がエージェントがツールを検出したメッセージをコンパクト化した後、エージェントは次にそれらのツールが必要になったときに再度検索します。 ツール検索は Claude がツールを検索するたびに 1 つの追加ラウンドトリップを追加しますが、大規模なツールセットの場合、これはすべてのターンでより小さいコンテキストによってオフセットされます。定義がコンテキストウィンドウに快適に収まる約 10 個未満のツールの場合、すべてを事前に読み込む方が通常は高速です。 基盤となる API メカニズムの詳細については、API のツール検索を参照してください。
ツール検索は Microsoft Foundry Azure でホストされているデプロイメントではサポートされていません。これらのデプロイメントはサーバー側でツール検索を拒否します。SDK はこの拒否を検出し、代わりにそのデプロイメント用にツール定義を事前に読み込みます。デプロイメント自体から拒否が来るため、ENABLE_TOOL_SEARCHはこれをオーバーライドできません。
ツール検索はデフォルトでオンです。SDK のサポートされていないモデルリストに含まれるモデルの場合、SDK はツール定義を事前に読み込み、ENABLE_TOOL_SEARCH 値はそれを上書きしません。Google Cloud の Agent Platform では、SDK はモデル世代によって決定します。
  • Claude Opus 4.5、Sonnet 4.5、Haiku 4.5、およびそれ以降: ツール検索はデフォルトでオンです。
  • 以前の Agent Platform モデル: SDK はツール定義を事前に読み込みます。これは、それらのサービングスタックが必要なベータヘッダーを拒否するためです。ENABLE_TOOL_SEARCH はこれを上書きできません。
Claude Code v2.1.221 より前は、ENABLE_TOOL_SEARCH を設定しない限り、SDK は Google Cloud の Agent Platform 上のすべてのモデルに対してツール検索を無効にしていました。 SDK は、ANTHROPIC_BASE_URL が非ファーストパーティホストを指す場合もツール検索を無効にします。ほとんどのプロキシは tool_reference ブロックを転送しないためです。ENABLE_TOOL_SEARCH 環境変数でそのデフォルトを上書きできます。 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS を設定するとツール検索がオフになります。ENABLE_TOOL_SEARCH を自分で設定してそれを上書きすることはできません。Claude Code v2.1.227 以降では、組織は管理設定を通じて、この変数が設定されている場合でもツール検索をオンに保つことができます。HIPAA 設定が適用されるセッションではツール検索はオフになり、ENABLE_TOOL_SEARCH でも管理設定でも再びオンにすることはできません。プレリリース機能を無効にするは、上書きが適用される場所と変数が削除する内容をカバーしています。 ツール検索は、リモート MCP サーバーから来るか、カスタム SDK MCP サーバーから来るかに関わらず、すべての登録ツールに適用されます。auto を使用する場合、SDK はツール検索が遅延できるすべての定義をカウントして、1 つの結合された閾値に向かってカウントします。alwaysLoadとマークされていない各 MCP ツール(任意のサーバーから)、およびオンデマンドで読み込まれる組み込みツール。SDK は Bash、Read、Edit などのコア組み込みツールを事前に読み込み、閾値に向かってカウントしません。プラグインのいずれかに含まれる mod も、ツールを遅延させたり事前に読み込んだりでき、それによってこのカウントが変わります。 query() の env オプションで値を設定します。TypeScript では、env はサブプロセス環境を置き換えるため、継承された変数を保持するために ...process.env を展開します。Python では、env は継承された環境の上にマージされます。この例は、多くのツールを公開するリモート MCP サーバーに接続し、ワイルドカードですべてのツールを事前承認し、auto:5 を使用して、ツール検索が遅延できる定義がコンテキストウィンドウの 5% に達するとツール検索をアクティブにします。
この例を実行するには、https://tools.example.com/mcp を独自の MCP サーバーの URL に置き換えてください。成功時に、結果テキストがコンソールに出力されます。 これは単一ショットの query() 呼び出しであるため、SDK はエラー結果を生成した後に発生するため、この例はループを try ブロックでラップします。実行が失敗した理由を確認するには、ループ内の結果メッセージの subtype(error_during_execution など)を確認してください。結果メッセージの詳細については、結果を処理するを参照してください。

ツール検出を最適化する

検索メカニズムは、ツール名と説明に対してクエリを照合します。search_slack_messages のような名前は、query_slack よりも広い範囲のリクエストに対して表示されます。「キーワード、チャネル、または日付範囲で Slack メッセージを検索」などの具体的なキーワードを含む説明は、「Slack をクエリ」などの一般的な説明よりも多くのクエリに一致します。 利用可能なツールカテゴリをリストするシステムプロンプトセクションを追加することもできます。これにより、エージェントは検索対象のツールの種類に関するコンテキストを取得します。TypeScript では systemPrompt オプション、Python では system_prompt を使用してテキストを渡します。claude_code プリセットで append を使用すると、プリセットのプロンプトを置き換えるのではなく、テキストを追加します。
システムプロンプトオプションの完全なセットについては、システムプロンプトの変更を参照してください。

制限

  • 最大ツール数: カタログ内の 10,000 個のツール
  • 検索結果: デフォルトでは検索ごとに最も関連性の高い 5 つのツールを返します
  • モデルサポート: Opus 4、Sonnet 4、Haiku 4.5、およびそれ以降のモデル。Google Cloud の Agent Platform では Opus 4.5、Sonnet 4.5、Haiku 4.5、およびそれ以降のモデル。それより前のモデルでは、ツール検索を設定するで説明しているとおり、SDK はツール定義を事前に読み込みます。