メインコンテンツへスキップ
ツール検索により、エージェントは数百または数千のツールを動的に検出し、オンデマンドで読み込むことで、それらと連携できます。すべてのツール定義をコンテキストウィンドウに事前に読み込む代わりに、エージェントはツールカタログを検索し、必要なツールのみを読み込みます。 このアプローチは、ツールライブラリがスケーリングするにつれて、2 つの課題を解決します。
  • コンテキスト効率: ツール定義はコンテキストウィンドウの大部分を消費する可能性があります(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ツール検索はオフです。すべてのツール定義がすべてのターンでコンテキストに読み込まれます。
ツール検索は、リモート MCP サーバーから来るか、カスタム SDK MCP サーバーから来るかに関わらず、すべての登録ツールに適用されます。auto を使用する場合、閾値はすべてのサーバー全体のすべてのツール定義の合計サイズに基づいています。 query()env オプションで値を設定します。この例は、多くのツールを公開するリモート MCP サーバーに接続し、ワイルドカードですべてのツールを事前承認し、auto:5 を使用して、ツール定義がコンテキストウィンドウの 5% を超える場合にツール検索をアクティブにします。
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and run the appropriate database query",
  options: {
    mcpServers: {
      "enterprise-tools": {
        // Connect to a remote MCP server
        type: "http",
        url: "https://tools.example.com/mcp"
      }
    },
    allowedTools: ["mcp__enterprise-tools__*"], // Wildcard pre-approves all tools from this server
    env: {
      ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when tools exceed 5% of context
    }
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}
ENABLE_TOOL_SEARCH"false" に設定すると、ツール検索が無効になり、すべてのツール定義がすべてのターンでコンテキストに読み込まれます。これにより検索ラウンドトリップが削除されます。ツールセットが小さい(約 10 個未満のツール)場合、定義がコンテキストウィンドウに快適に収まる場合は、より高速になる可能性があります。

ツール検出を最適化する

検索メカニズムは、ツール名と説明に対してクエリを照合します。search_slack_messages のような名前は、query_slack よりも広い範囲のリクエストに対して表示されます。「キーワード、チャネル、または日付範囲で Slack メッセージを検索」などの具体的なキーワードを含む説明は、「Slack をクエリ」などの一般的な説明よりも多くのクエリに一致します。 利用可能なツールカテゴリをリストするシステムプロンプトセクションを追加することもできます。これにより、エージェントは検索対象のツールの種類に関するコンテキストを取得します。
You can search for tools to interact with Slack, GitHub, and Jira.

制限

  • 最大ツール数: カタログ内の 10,000 個のツール
  • 検索結果: 検索ごとに最も関連性の高い 3~5 個のツールを返します
  • モデルサポート: Claude Sonnet 4 以降、Claude Opus 4 以降(Haiku なし)

関連ドキュメント