ツール検索ツール

ツール検索ツール（tool search tool）を使用すると、Claudeはツールをオンデマンドで発見して読み込むことで、数百から数千のツールを扱えるようになります。すべてのツール定義を最初から「context window」（コンテキストウィンドウ）に読み込むのではなく、Claudeはツールカタログ（ツール名、説明、引数名、引数の説明を含む）を検索し、必要なツールだけを読み込みます。

すべてのツール定義を最初に読み込むと、ツールライブラリが大きくなるにつれて2つの問題が発生します。

• コンテキストの肥大化： 典型的なマルチサーバー構成（GitHub、Slack、Sentry、Grafana、Splunk）では、Claudeが何か作業を行う前に、定義だけで約55kトークンを消費することがあります。ツール検索は通常これを85パーセント以上削減し、特定のリクエストに対してClaudeが必要とする3〜5個のツールだけを読み込みます。
• ツール選択の精度： 利用可能なツールが30〜50個を超えると、Claudeが適切なツールを選ぶ能力は低下します。ツール検索は関連性の高いツールの絞り込まれたセットだけをオンデマンドで読み込むため、数千のツールがあっても選択精度は高く保たれます。

ツール検索をサポートするモデルについては、モデルの互換性を参照してください。

ツール検索はサーバーサイドツールとして実行されますが、独自のクライアントサイドのツール検索を実装することもできます。詳細については、カスタムツール検索の実装を参照してください。

モデルの互換性

両方のツール検索バリアントは、以下のモデルで利用できます。

Claude Opus 4.1以前のモデルは、ツール検索ツールをサポートしていません。

ツール検索の仕組み

ツール検索には2つのバリアントがあります。

• Regex（tool_search_tool_regex_20251119）：Claudeは正規表現パターンを構築してツールを検索します。
• BM25（tool_search_tool_bm25_20251119）：Claudeは自然言語クエリを使用してツールを検索します。

ツール検索ツールを有効にすると、次のように動作します。

1. toolsリストにツール検索ツール（たとえば、tool_search_tool_regex_20251119またはtool_search_tool_bm25_20251119）を含めます。
2. tools配列にすべてのツール定義を指定し、最初に読み込むべきでないツールにはdefer_loading: trueを設定します。少なくとも1つのツール（通常はツール検索ツール自体）は非遅延のままにする必要があります。
3. 初期状態では、Claudeのコンテキストにはツール検索ツールと非遅延のツールのみが含まれます。
4. Claudeが追加のツールを必要とする場合、ツール検索ツールを使用して検索します。
5. APIが検索を実行し、一致するツールをtool_referenceブロックとして返します（デフォルトでは最大5件。Claudeは検索入力でlimitを設定できます）。
6. APIはこれらの参照を完全なツール定義に自動的に展開します。
7. Claudeは発見されたツールの中から選択して呼び出します。

クイックスタート

次の例には、ツール検索ツールと2つの遅延ツールが含まれています。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=2048,
    messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {
            "name": "get_weather",
            "description": "Get the weather at a specific location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["location"],
            },
            "defer_loading": True,
        },
        {
            "name": "search_files",
            "description": "Search through files in the workspace",
            "input_schema": {
                "type": "object",
                "properties": {
                    "query": {"type": "string"},
                    "file_types": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["query"],
            },
            "defer_loading": True,
        },
    ],
)

print(response)

Claudeはカタログを検索し、get_weatherを発見して呼び出します。レスポンスはstop_reason: "tool_use"で終了します。ツール呼び出しの処理と同様に、発見されたツールを実行してtool_resultを返してください。レスポンス形式では、返されるブロックと次に送信すべき内容を示しています。

ツール定義

ツール検索ツールには2つのバリアントがあります。

{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}

{
  "type": "tool_search_tool_bm25_20251119",
  "name": "tool_search_tool_bm25"
}

遅延ツール読み込み

defer_loading: trueを追加して、ツールをオンデマンド読み込みの対象としてマークします。

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["location"]
  },
  "defer_loading": true
}

defer_loadingは、リクエストで何を送信するかではなく、何がコンテキストウィンドウに入るかを制御します。

• 遅延ツールを含め、すべてのツールの完全な定義を毎回のリクエストでtools配列に送信する必要があります。APIは検索を実行し、tool_referenceブロックを展開するために、サーバーサイドでそれらを必要とします。
• defer_loadingのないツールは、すぐにコンテキストに読み込まれます。
• defer_loading: trueのツールは、Claudeが検索を通じて発見した場合にのみ読み込まれます。
• ツール検索ツール自体には決してdefer_loading: trueを設定しないでください。
• 最も頻繁に使用する3〜5個のツールは非遅延のままにして、Claudeが最初に検索せずに呼び出せるようにしてください。

コンピュータ使用およびブラウザ使用のツールセット（computer_toolset_20260801およびbrowser_toolset_20260801）は、エントリ自体ではなく、エントリのconfigsオブジェクト内でメンバーツールごとにdefer_loadingを受け取ります。エントリレベルで設定したリクエストは拒否されます。ツールセットは1つの単位として遅延および展開されるため、defer_loadingは有効なすべてのメンバーで同じ値に解決される必要があり、Claudeが検索を通じてツールセットを発見すると、有効なすべてのメンバーが一度に読み込まれます。configsの形式については、クライアントツールセットを参照してください。

両方のツール検索バリアント（regexとbm25）は、ツール名、説明、引数名、引数の説明を検索します。

内部的には、APIは遅延ツールをシステムプロンプトのプレフィックスから除外します。Claudeがツール検索を通じて遅延ツールを発見すると、APIは会話内にインラインでtool_referenceブロックを追加し、Claudeに渡す前にそれを完全なツール定義に展開します。プレフィックスは変更されないため、「prompt caching」（プロンプトキャッシング）は維持されます。strictモードの文法（ツール呼び出しの出力をスキーマに一致するよう制約するルール）は完全なツールセットから構築されるため、defer_loadingとstrictモードは文法の再コンパイルなしで組み合わせることができます。

レスポンス形式

Claudeがツール検索ツールを使用すると、レスポンスには次のブロックタイプが含まれます。

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll search for tools to help with the weather information."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01ABC123",
      "name": "tool_search_tool_regex",
      "input": {
        "pattern": "weather",
        "limit": 10
      }
    },
    {
      "type": "tool_search_tool_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": {
        "type": "tool_search_tool_search_result",
        "tool_references": [{ "type": "tool_reference", "tool_name": "get_weather" }]
      }
    },
    {
      "type": "text",
      "text": "I found a weather tool. Let me get the weather for San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01XYZ789",
      "name": "get_weather",
      "input": { "location": "San Francisco", "unit": "fahrenheit" }
    }
  ],
  "stop_reason": "tool_use"
}

レスポンスの理解

• server_tool_use： Claudeによるツール検索ツールの呼び出しです。検索はAnthropicのサーバー上で実行されます。そのsrvtoolu_... IDに対してtool_resultを返さないでください。inputには検索内容（regexバリアントの場合はpattern、BM25の場合はquery）が含まれ、オプションのlimitを含む場合があります。limitは1から10,000までの整数で、検索が返す一致ツールの数の上限を設定します（デフォルト：5）。
• tool_search_tool_result： ネストされたtool_search_tool_search_resultオブジェクト内の検索結果です。メッセージ履歴にそのまま保持してください。
• tool_references： 発見されたツールを指すtool_referenceオブジェクトの配列です。APIがClaudeのためにこれらを展開します。自分で展開することはありません。
• tool_use： Claudeによる発見されたツールの呼び出しです。標準のツール使用とまったく同じように、実行してtool_resultを返してください。

APIは、Claudeに表示する前にtool_referenceブロックを完全なツール定義に自動的に展開します。一致するすべてのツール定義をtoolsパラメータで提供している限り、この展開を自分で処理する必要はありません。

会話の継続

次のリクエストでは、server_tool_useブロックとtool_search_tool_resultブロックを含め、アシスタントのコンテンツを変更せずにそのまま渡します。発見されたツールに対するtool_resultをユーザーメッセージに追加し、同じtools配列（検索ツールとすべての遅延定義）を送信します。srvtoolu_... IDに対してtool_resultを返さないでください。APIはそのリクエストを拒否します。APIは会話履歴全体でtool_referenceブロックを展開するため、Claudeは再検索せずに後のターンで発見済みのツールを再利用できます。何にも一致しない検索は、エラーではなく、空のtool_references配列を持つtool_search_tool_search_resultを返します。

MCP統合

ツールがMCPコネクタを通じてMCPサーバーから提供される場合、個々のツール定義にdefer_loadingを設定しません。代わりに、サーバー全体に対してmcp_toolsetエントリのdefault_configで一度設定するか、configsでツールごとに設定します。MCPツールセットの設定を参照してください。

カスタムツール検索の実装

カスタムツールからtool_referenceブロックを返すことで、独自のツール検索ロジック（たとえば、埋め込みやセマンティック検索を使用）を実装できます。Claudeがカスタム検索ツールを呼び出したら、content配列にtool_referenceブロックを含む標準のtool_resultを返します。

{
  "type": "tool_result",
  "tool_use_id": "toolu_your_tool_id",
  "content": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}

参照されるすべてのツールには、トップレベルのtoolsパラメータに対応するツール定義が必要であり、通常はdefer_loading: trueを設定します。これにより、埋め込みベースの検索など、組み込みバリアントが提供しない検索方法を使用でき、APIは返されたtool_referenceブロックを同じ方法で展開します。

埋め込みを使用した完全な例については、埋め込みによるツール検索のレシピを参照してください。

エラー処理

HTTPエラー（400ステータス）

これらのエラーは、APIによるリクエストの処理を妨げます。

すべてのツールが遅延されている場合：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "At least one tool must have defer_loading=false. All tools cannot be deferred."
  }
}

ツール定義が欠落している場合：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' not found in available tools"
  }
}

ツール結果エラー（200ステータス）

実行中にツール検索操作が失敗した場合、APIは本文にエラーを含む200レスポンスを返します。

{
  "type": "tool_search_tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_tool_input",
    "error_message": "Invalid regular expression pattern: missing ) at position 1"
  }
}

error_codeフィールドには4つの値があります。

• invalid_tool_input：検索入力が無効でした。たとえば、不正な形式の正規表現パターンや、200文字の制限を超えるパターンなどです
• unavailable：検索を実行できませんでした。たとえば、タイムアウトした場合やサービスが利用できなかった場合などです
• too_many_requests：ツール検索操作のレート制限を超えました
• execution_time_exceeded：検索が実行時間の制限を超えました

よくある間違い

{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}

{
  "name": "my_tool",
  "description": "Full description here",
  "input_schema": {
    "type": "object"
  },
  "defer_loading": true
}

プロンプトキャッシング

defer_loadingがプロンプトキャッシングをどのように維持するかについては、プロンプトキャッシングを使用したツール使用を参照してください。

defer_loading: trueのツールにcache_controlを同時に設定することはできません。APIは400を返します。キャッシュブレークポイントは非遅延のツールに配置してください。

ストリーミング

ストリーミングを有効にすると、ストリームの一部としてツール検索イベントを受信します。

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "tool_search_tool_regex"}}

// Search pattern streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"pattern\":\"weather\"}"}}

// Pause while search executes

// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "tool_search_tool_search_result", "tool_references": [{"type": "tool_reference", "tool_name": "get_weather"}]}}}

// Claude continues with discovered tools

バッチリクエスト

Messages Batches APIにツール検索ツールを含めることができます。

制限とベストプラクティス

制限

• 遅延ツールの最大数： リクエストごとにdefer_loading: trueのツールは10,000個まで
• 検索結果： 各検索はデフォルトで最大5件の一致ツールを返します。Claudeは検索入力でlimitを1から10,000までの任意の整数に設定できます
• パターンとクエリの長さ： 正規表現パターンは最大200文字、BM25クエリは最大500文字
• モデルのサポート： モデルの互換性を参照してください

ツール検索を使用すべき場合

次のいずれかに該当する場合は、ツール検索を使用してください。

• 利用可能なツールが10個以上ある。
• ツール定義が10kトークン以上を消費する。
• ツールセットが大きくなるにつれてツール選択の精度が低下する。
• 複数のMCPサーバーを集約している（200個以上のツール）。
• ツールライブラリが時間とともに増加する。

ツールが10個未満の場合、すべてのリクエストですべてのツールが使用される場合、またはツール定義が小さい場合（合計100トークン未満）は、ツール検索を使用しない標準のツール呼び出しの方が適しています。

最適化のヒント

• 最も頻繁に使用する3〜5個のツールは非遅延のままにします。
• 明確で説明的なツール名と説明を記述します。
• ツール名に一貫した名前空間を使用します。サービスまたはリソースごとにプレフィックスを付け（たとえば、github_、slack_）、1回の検索でグループ全体に一致するようにします。
• ユーザーがタスクを説明する方法に一致するキーワードを説明に使用します。
• 利用可能なツールカテゴリを説明するシステムプロンプトのセクションを追加します：「Slack、GitHub、Jiraとやり取りするためのツールを検索できます。」
• Claudeがどのツールを発見するかを監視して、説明を改善します。

使用量

ツール検索は、個別のサーバーツールとして計測されません。レスポンスのusage.server_tool_useオブジェクトにはツール検索のフィールドはなく、検索によってコンテキストに読み込まれたツール定義は、他のツール定義と同様に入力トークンとしてカウントされます。

次のステップ