ツール検索ツール

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

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

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

ツール検索はClaude APIで一般提供されています。サポートされているモデルについては、モデルの互換性を参照してください。

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



モデルの互換性

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

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個）。
6. APIがこれらの参照を完全なツール定義に自動的に展開します。
7. Claudeが発見されたツールから選択して呼び出します。



クイックスタート

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-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が最初に検索せずに呼び出せるようにします。

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

内部的には、APIはシステムプロンプトのプレフィックスから遅延ツールを除外します。Claudeがツール検索を通じて遅延ツールを発見すると、APIは会話内にインラインでtool_referenceブロックを追加し、Claudeに渡す前に完全なツール定義に展開します。プレフィックスは変更されないため、プロンプトキャッシングは保持されます。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"
      }
    },
    {
      "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を返さないでください。
• 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がカスタム検索ツールを呼び出したら、コンテンツ配列に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: 検索が実行時間の制限を超過しました



よくある間違い



プロンプトキャッシング

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個の一致するツールを返します
• パターンとクエリの長さ: 正規表現パターンは最大200文字、BM25クエリは最大500文字
• モデルサポート: モデルの互換性を参照してください



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

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

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

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



最適化のヒント

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



使用量

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



次のステップ