ツール検索ツール

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

このアプローチは、ツールライブラリが拡張するにつれて急速に複合する2つの問題を解決します：

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

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

独自の検索実装からtool_referenceブロックを返すことで、クライアントサイドのツール検索を実装することもできます。

ツール検索の仕組み

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

• Regex (tool_search_tool_regex_20251119)：Claudeがツールを検索するためのregexパターンを構築します
• BM25 (tool_search_tool_bm25_20251119)：Claudeが自然言語クエリを使用してツールを検索します

ツール検索ツールを有効にすると：

1. ツールリストにツール検索ツール（例：tool_search_tool_regex_20251119またはtool_search_tool_bm25_20251119）を含めます
2. すぐにロードすべきでないツールにはdefer_loading: trueを付けてすべてのツール定義を提供します
3. Claudeは最初にツール検索ツールと非遅延ツールのみを認識します
4. Claudeが追加のツールを必要とする場合、ツール検索ツールを使用して検索します
5. APIが最も関連性の高い3〜5つのtool_referenceブロックを返します
6. これらの参照は自動的に完全なツール定義に展開されます
7. Claudeは発見されたツールから選択して呼び出します

これにより、高いツール選択精度を維持しながらコンテキストウィンドウを効率的に保ちます。

クイックスタート

遅延ツールを使用した簡単な例を示します：

ツール定義

ツール検索ツールには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のないツールはすぐにコンテキストにロードされます
• defer_loading: trueのツールは、Claudeが検索で発見した場合にのみロードされます
• ツール検索ツール自体には絶対にdefer_loading: trueを設定しないでください
• 最適なパフォーマンスのために、最もよく使用される3〜5つのツールを非遅延のままにしてください

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

遅延の内部動作： 遅延ツールはシステムプロンプトプレフィックスに含まれません。モデルがツール検索を通じて遅延ツールを発見すると、ツール定義は会話内にインラインでtool_referenceブロックとして追加されます。プレフィックスは変更されないため、プロンプトキャッシングが保持されます。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": {
        "query": "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がツール検索ツールを呼び出していることを示します
• tool_search_tool_result： ネストされたtool_search_tool_search_resultオブジェクトを含む検索結果を含みます
• tool_references： 発見されたツールを指すtool_referenceオブジェクトの配列
• tool_use： Claudeが発見されたツールを呼び出しています

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

MCP統合

defer_loadingを使用したmcp_toolsetの設定については、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" }]
}

参照されるすべてのツールは、defer_loading: trueを付けてトップレベルのtoolsパラメータに対応するツール定義が必要です。このアプローチにより、ツール検索システムとの互換性を維持しながら、より高度な検索アルゴリズムを使用できます。

埋め込みを使用した完全な例については、埋め込みを使用したツール検索クックブックを参照してください。

エラー処理

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

これらのエラーはリクエストの処理を妨げます：

すべてのツールが遅延設定：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "All tools have defer_loading set. At least one tool must be non-deferred."
  }
}

ツール定義の欠落：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' has no corresponding tool definition"
  }
}

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

ツール実行中のエラーは、本文にエラー情報を含む200レスポンスを返します：

{
  "type": "tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_pattern"
  }
}

エラーコード：

• too_many_requests：ツール検索操作のレート制限を超過
• invalid_pattern：不正なregexパターン
• pattern_too_long：パターンが200文字の制限を超過
• unavailable：ツール検索サービスが一時的に利用不可

よくある間違い

プロンプトキャッシング

defer_loadingがプロンプトキャッシングを保持する方法については、プロンプトキャッシングを使用したツール使用を参照してください。

システムは会話履歴全体にわたってtool_referenceブロックを自動的に展開するため、Claudeは再検索することなく後続のターンで発見されたツールを再利用できます。

ストリーミング

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

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"}}

// 検索クエリがストリーミング
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}}

// 検索実行中に一時停止

// 検索結果がストリーミング
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が発見されたツールで続行

バッチリクエスト

Messages Batches APIにツール検索ツールを含めることができます。Messages Batches APIを通じたツール検索操作は、通常のMessages APIリクエストと同じ価格で提供されます。

データ保持

サーバーサイドのツール検索（tool_searchツール）は、即時のAPIレスポンスを超えてツールカタログデータ（ツール名、説明、引数メタデータ）をインデックス化して保存します。このカタログデータはAnthropicの標準保持ポリシーに従って保持されます。標準のMessages APIを使用するカスタムクライアントサイドのツール検索実装は、完全にZDR対応です。

すべての機能にわたるZDR適格性については、APIとデータ保持を参照してください。

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

制限

• 最大ツール数： カタログ内10,000ツール
• 検索結果： 検索ごとに最も関連性の高い3〜5つのツールを返します
• パターン長： regexパターンの最大200文字
• モデルサポート： Claude Mythos Preview、Sonnet 4.0以上、Opus 4.0以上のみ（Haikuは非対応）

ツール検索を使用する場合

適切なユースケース：

• システムに10以上のツールが利用可能
• ツール定義が10kトークン以上を消費している
• 大規模なツールセットでツール選択精度の問題が発生している
• 複数のサーバー（200以上のツール）を持つMCPを活用したシステムを構築している
• ツールライブラリが時間とともに成長している

従来のツール呼び出しの方が適している場合：

• 合計10未満のツール
• すべてのツールがすべてのリクエストで頻繁に使用される
• 非常に小さなツール定義（合計<100トークン）

最適化のヒント

• 最もよく使用される3〜5つのツールを非遅延のままにする
• 明確で説明的なツール名と説明を書く
• ツール名に一貫した名前空間を使用する：サービスまたはリソースでプレフィックスを付ける（例：github_、slack_）ことで、検索クエリが自然に適切なツールグループを見つけられるようにする
• ユーザーがタスクを説明する方法に合致するセマンティックキーワードを説明に使用する
• 利用可能なツールカテゴリを説明するシステムプロンプトセクションを追加する：「Slack、GitHub、Jiraと連携するためのツールを検索できます」
• Claudeが発見するツールを監視して説明を改善する

使用量

ツール検索ツールの使用量はレスポンスの使用量オブジェクトで追跡されます：

{
  "usage": {
    "input_tokens": 1024,
    "output_tokens": 256,
    "server_tool_use": {
      "tool_search_requests": 2
    }
  }
}

次のステップ