ツール検索ツール

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

このアプローチは、ツールライブラリのスケーリングに伴い急速に複合する2つの問題を解決します：

• コンテキストの肥大化： ツール定義はコンテキスト予算を急速に消費します。典型的なマルチサーバーセットアップ（GitHub、Slack、Sentry、Grafana、Splunk）は、Claudeが実際の作業を行う前に定義だけで約55kトークンを消費できます。ツール検索は通常これを85%以上削減し、Claudeが実際に必要とする3～5個のツールのみを読み込みます。
• ツール選択の精度： 利用可能なツールが30～50個を超えると、Claudeが正しいツールを選択する能力は大幅に低下します。オンデマンドで関連するツールの焦点を絞ったセットを表示することで、ツール検索は数千のツール全体でも選択精度を高く保ちます。

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

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

ツール検索の仕組み

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

• Regex (tool_search_tool_regex_20251119)：Claudeはツールを検索するための正規表現パターンを構築します
• 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ブロックとしてインラインで追加されます。プレフィックスは変更されないため、プロンプトキャッシングが保持されます。厳密モードの文法は完全なツールセットから構築されるため、defer_loadingと厳密モードは文法の再コンパイルなしで構成されます。

レスポンス形式

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 connectorを参照してください。

カスタムツール検索実装

独自のツール検索ロジック（例：埋め込みやセマンティック検索を使用）を実装し、カスタムツールから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を指定した対応するツール定義を持つ必要があります。このアプローチにより、ツール検索システムとの互換性を維持しながら、より洗練された検索アルゴリズムを使用できます。

埋め込みを使用した完全な例については、tool search with embeddings cookbookを参照してください。

エラーハンドリング

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：不正な形式の正規表現パターン
• pattern_too_long：パターンが200文字制限を超えています
• unavailable：ツール検索サービスが一時的に利用不可です

一般的な間違い

プロンプトキャッシング

defer_loadingがプロンプトキャッシングを保持する方法については、Tool use with prompt cachingを参照してください。

システムは会話履歴全体を通じて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"}}

// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"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にツール検索ツールを含めることができます。Messages Batches API経由のツール検索操作は、通常のMessages APIリクエストと同じ価格です。

データ保持

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

すべてのフィーチャー全体のZDR対応については、API and data retentionを参照してください。

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

制限

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

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

良いユースケース：

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

従来のツール呼び出しがより良い場合：

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

最適化のヒント

• 最も頻繁に使用される3～5個のツールを遅延されていないものとして保ちます
• 明確で説明的なツール名と説明を書きます
• ツール名で一貫した名前空間を使用します：サービスまたはリソースでプレフィックスを付けます（例：github_、slack_）。これにより、検索クエリが自然に正しいツールグループを表示します
• ユーザーがタスクを説明する方法と一致するセマンティックキーワードを説明に使用します
• 利用可能なツールカテゴリを説明するシステムプロンプトセクションを追加します：「Slack、GitHub、Jiraと対話するためのツールを検索できます」
• Claudeが検出するツールを監視して、説明を改善します

使用法

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

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

次のステップ