ツール検索ツール

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

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

• コンテキストの肥大化： 一般的なマルチサーバー構成（GitHub、Slack、Sentry、Grafana、Splunk）では、Claudeが作業を開始する前に定義だけで約55kトークンを消費する可能性があります。ツール検索は通常これを85%以上削減し、特定のリクエストに必要な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-4-8",
    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 mode（ツール呼び出しの出力をスキーマに一致するよう制約するルール）の文法は完全なツールセットから構築されるため、defer_loadingとstrict modeは文法の再コンパイルなしで組み合わせられます。



レスポンス形式

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オブジェクトにはツール検索フィールドがなく、検索がコンテキストに読み込むツール定義は、他のツール定義と同様に入力トークンとしてカウントされます。



次のステップ