- コンテキスト効率: ツール定義はコンテキストウィンドウの大部分を消費する可能性があります(50 個のツールは 10~20K トークンを使用できます)。実際の作業用のスペースが減少します。
- ツール選択精度: 30~50 個以上のツールが一度に読み込まれると、ツール選択精度が低下します。
ツール検索の仕組み
ツール検索がアクティブな場合、ツール定義はコンテキストウィンドウから保留されます。エージェントは利用可能なツールの概要を受け取り、タスクが既に読み込まれていない機能を必要とする場合、関連するツールを検索します。最も関連性の高い 3~5 個のツールがコンテキストに読み込まれ、その後のターンで利用可能なままになります。会話が十分に長く、SDK が以前のメッセージをコンパクト化してスペースを解放する場合、以前に検出されたツールが削除される可能性があり、エージェントは必要に応じて再度検索します。 ツール検索は、Claude が初めてツールを検出するときに 1 つの追加ラウンドトリップを追加します(検索ステップ)。ただし、大規模なツールセットの場合、これはすべてのターンでより小さいコンテキストによってオフセットされます。ツールが約 10 個未満の場合、すべてを事前に読み込む方が通常は高速です。 基盤となる API メカニズムの詳細については、API のツール検索を参照してください。ツール検索には Claude Sonnet 4 以降または Claude Opus 4 以降が必要です。Haiku モデルはツール検索をサポートしていません。
ツール検索を設定する
ツール検索はデフォルトでオンです。Vertex AI ではデフォルトで無効になっており、Claude Sonnet 4.5 以降および Claude Opus 4.5 以降でサポートされています。また、ANTHROPIC_BASE_URL が非ファーストパーティホストを指す場合も無効になります。ほとんどのプロキシは tool_reference ブロックを転送しないためです。ENABLE_TOOL_SEARCH 環境変数でいずれかのデフォルトをオーバーライドできます。
| 値 | 動作 |
|---|---|
| (未設定) | ツール検索はオンです。ツール定義は遅延され、オンデマンドで検出されます。Vertex AI または非ファーストパーティ ANTHROPIC_BASE_URL では事前読み込みにフォールバックします。 |
true | ツール検索は常にオンです。SDK は Vertex AI およびプロキシ経由でもベータヘッダーを送信します。Sonnet 4.5 または Opus 4.5 より前の Vertex AI モデル、または tool_reference ブロックをサポートしないプロキシでは、リクエストが失敗します。 |
auto | すべてのツール定義の合計トークン数をモデルのコンテキストウィンドウと照合します。コンテキストウィンドウの 10% を超える場合、ツール検索がアクティブになります。10% 未満の場合、すべてのツールが通常どおりコンテキストに読み込まれます。 |
auto:N | カスタム割合を使用した auto と同じです。auto:5 はツール定義がコンテキストウィンドウの 5% を超える場合にアクティブになります。値が低いほど、より早くアクティブになります。 |
false | ツール検索はオフです。すべてのツール定義がすべてのターンでコンテキストに読み込まれます。 |
auto を使用する場合、閾値はすべてのサーバー全体のすべてのツール定義の合計サイズに基づいています。
query() の env オプションで値を設定します。この例は、多くのツールを公開するリモート MCP サーバーに接続し、ワイルドカードですべてのツールを事前承認し、auto:5 を使用して、ツール定義がコンテキストウィンドウの 5% を超える場合にツール検索をアクティブにします。
ENABLE_TOOL_SEARCH を "false" に設定すると、ツール検索が無効になり、すべてのツール定義がすべてのターンでコンテキストに読み込まれます。これにより検索ラウンドトリップが削除されます。ツールセットが小さい(約 10 個未満のツール)場合、定義がコンテキストウィンドウに快適に収まる場合は、より高速になる可能性があります。
ツール検出を最適化する
検索メカニズムは、ツール名と説明に対してクエリを照合します。search_slack_messages のような名前は、query_slack よりも広い範囲のリクエストに対して表示されます。「キーワード、チャネル、または日付範囲で Slack メッセージを検索」などの具体的なキーワードを含む説明は、「Slack をクエリ」などの一般的な説明よりも多くのクエリに一致します。
利用可能なツールカテゴリをリストするシステムプロンプトセクションを追加することもできます。これにより、エージェントは検索対象のツールの種類に関するコンテキストを取得します。
制限
- 最大ツール数: カタログ内の 10,000 個のツール
- 検索結果: 検索ごとに最も関連性の高い 3~5 個のツールを返します
- モデルサポート: Claude Sonnet 4 以降、Claude Opus 4 以降(Haiku なし)
関連ドキュメント
- API のツール検索:カスタム実装を含むツール検索の完全な API ドキュメント
- MCP サーバーを接続する:MCP サーバー経由で外部ツールに接続する
- カスタムツール:SDK MCP サーバーで独自のツールを構築する
- TypeScript SDK リファレンス:完全な API リファレンス
- Python SDK リファレンス:完全な API リファレンス