- コンテキスト効率： ツール定義はコンテキストウィンドウの大部分を消費する可能性があります（50 個のツールは 10～20K トークンを使用できます）。実際の作業用のスペースが減少します。
- ツール選択精度： 30～50 個以上のツールが一度に読み込まれると、ツール選択精度が低下します。
ツール検索の仕組み
ツール検索がアクティブな場合、ツール定義はコンテキストウィンドウから保留されます。エージェントは利用可能なツールの概要を受け取り、タスクが既に読み込まれていない機能を必要とする場合、関連するツールを検索します。最も関連性の高い 5 個までのツールがデフォルトでコンテキストに読み込まれ、その後のターンで利用可能なままになります。会話が十分に長く、SDK が以前のメッセージをコンパクト化してスペースを解放する場合、以前に検出されたツールが削除される可能性があり、エージェントは必要に応じて再度検索します。 ツール検索は、Claude が初めてツールを検出するときに 1 つの追加ラウンドトリップを追加します（検索ステップ）。ただし、大規模なツールセットの場合、これはすべてのターンでより小さいコンテキストによってオフセットされます。ツールが約 10 個未満の場合、すべてを事前に読み込む方が通常は高速です。 基盤となる API メカニズムの詳細については、API のツール検索を参照してください。ツール検索は Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.5、およびそれ以降のモデルでサポートされています。現在のリストについては、API ドキュメントのモデル互換性を参照してください。Google Cloud の Agent Platform では、サポートされている最小モデルは Claude Sonnet 4.5 と Claude Opus 4.5 です。
ツール検索を設定する
ツール検索はデフォルトでオンです。Google Cloud の Agent Platform ではデフォルトで無効になっており、Claude Sonnet 4.5 以降および Claude Opus 4.5 以降でサポートされています。また、ANTHROPIC_BASE_URL が非ファーストパーティホストを指す場合も無効になります。ほとんどのプロキシは tool_reference ブロックを転送しないためです。ENABLE_TOOL_SEARCH 環境変数でいずれかのデフォルトをオーバーライドできます。
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS を設定するとツール検索がオフになり、ENABLE_TOOL_SEARCH はそれをオーバーライドできません。この変数は、defer_loading ツール定義と tool_reference コンテンツブロックが必要とするベータヘッダーを削除します。
ツール検索は、リモート MCP サーバーから来るか、カスタム SDK MCP サーバーから来るかに関わらず、すべての登録ツールに適用されます。auto を使用する場合、閾値はすべてのサーバー全体のすべてのツール定義の合計サイズに基づいています。
query() の env オプションで値を設定します。TypeScript では、env はサブプロセス環境を置き換えるため、継承された変数を保持するために ...process.env を展開します。Python では、env は継承された環境の上にマージされます。この例は、多くのツールを公開するリモート MCP サーバーに接続し、ワイルドカードですべてのツールを事前承認し、auto:5 を使用して、ツール定義がコンテキストウィンドウの 5% を超える場合にツール検索をアクティブにします。