ツール検索ツール

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

このアプローチは、ツールライブラリが拡大する際の2つの重要な課題を解決します：

コンテキスト効率: ツール定義はコンテキストウィンドウの大部分を消費する可能性があり（50ツール ≈ 10-20Kトークン）、実際の作業に使える余地が少なくなります
ツール選択精度: 従来の方法で利用可能なツールが30-50を超えると、Claudeが正しくツールを選択する能力が大幅に低下します

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

この機能に関するフィードバックをフィードバックフォームからお寄せください。

サーバーサイドツール検索はゼロデータリテンション（ZDR）の対象外です。データは機能の標準保持ポリシーに従って保持されます。カスタムクライアントサイドツール検索の実装は標準のMessages APIを使用し、ZDRの対象となります。

Amazon Bedrockでは、サーバーサイドツール検索はinvoke API経由でのみ利用可能で、 converse APIでは利用できません。

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

ツール検索の仕組み

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

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

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

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

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

クイックスタート

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

ツール定義

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

JSON

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

JSON

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

Regexバリアントのクエリ形式：Python正規表現であり、自然言語ではありません

tool_search_tool_regex_20251119を使用する場合、ClaudeはPythonのre.search()構文を使用して正規表現パターンを構築します。自然言語クエリではありません。一般的なパターン：

"weather" - "weather"を含むツール名/説明にマッチ
"get_.*_data" - get_user_data、get_weather_dataなどのツールにマッチ
"database.*query|query.*database" - 柔軟性のためのORパターン
"(?i)slack" - 大文字小文字を区別しない検索

最大クエリ長：200文字

BM25バリアントのクエリ形式：自然言語

tool_search_tool_bm25_20251119を使用する場合、Claudeは自然言語クエリを使用してツールを検索します。

遅延ツール読み込み

defer_loading: trueを追加して、オンデマンド読み込み用にツールをマークします：

JSON

{
  "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）は、ツール名、説明、引数名、引数の説明を検索します。

レスポンス形式

Claudeがツール検索ツールを使用すると、レスポンスに新しいブロックタイプが含まれます：

JSON

{
  "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統合

ツール検索ツールはMCPサーバーと連携します。APIリクエストに"mcp-client-2025-11-20"ベータヘッダーを追加し、mcp_toolsetとdefault_configを使用してMCPツールの読み込みを遅延させます：

MCP設定オプション：

default_config.defer_loading: MCPサーバーからのすべてのツールのデフォルトを設定
configs: 名前で特定のツールのデフォルトをオーバーライド
複数のMCPサーバーとツール検索を組み合わせて大規模なツールライブラリに対応

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

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

JSON

{
  "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_tool_result形式は、Anthropicの組み込みツール検索が内部的に使用するサーバーサイド形式です。カスタムクライアントサイド実装では、上記のようにtool_referenceコンテンツブロックを含む標準のtool_result形式を常に使用してください。

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

エラー処理

ツール検索ツールはツール使用の例と互換性がありません。ツール使用の例を提供する必要がある場合は、ツール検索なしの標準的なツール呼び出しを使用してください。

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レスポンスを返します：

JSON

{
  "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: ツール検索サービスが一時的に利用不可

よくある間違い

プロンプトキャッシング

ツール検索はプロンプトキャッシングと連携します。cache_controlブレークポイントを追加して、マルチターン会話を最適化します：

Python

import anthropic

client = anthropic.Anthropic()

# ツール検索を使用した最初のリクエスト
messages = [{"role": "user", "content": "What's the weather in Seattle?"}]

response1 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=2048,
    messages=messages,
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"],
            },
            "defer_loading": True,
        },
    ],
)

# Claudeのレスポンスを会話に追加
messages.append({"role": "assistant", "content": response1.content})

# キャッシュブレークポイントを含む2番目のリクエスト
messages.append(
    {
        "role": "user",
        "content": "What about New York?",
        "cache_control": {"type": "ephemeral"},
    }
)

response2 = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=2048,
    messages=messages,
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"],
            },
            "defer_loading": True,
        },
    ],
)

print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

システムは会話履歴全体で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リクエストと同じ価格設定です。

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

制限

最大ツール数: カタログ内に10,000ツール
検索結果: 検索ごとに最も関連性の高い3-5個のツールを返します
パターン長: 正規表現パターンの最大200文字
モデルサポート: Sonnet 4.0+、Opus 4.0+のみ（Haikuは非対応）

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

適したユースケース：

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

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

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

最適化のヒント

最も頻繁に使用する3-5個のツールを非遅延のままにする
明確で説明的なツール名と説明を記述する
ユーザーがタスクを説明する方法に一致するセマンティックキーワードを説明に使用する
利用可能なツールカテゴリを説明するシステムプロンプトセクションを追加する：「Slack、GitHub、Jiraと連携するツールを検索できます」
Claudeが検出するツールを監視して説明を改善する

使用量

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

JSON

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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
            }
        ]
    }'

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: mcp-client-2025-11-20" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-opus-4-6",
    "max_tokens": 2048,
    "mcp_servers": [
      {
        "type": "url",
        "name": "database-server",
        "url": "https://mcp-db.example.com"
      }
    ],
    "tools": [
      {
        "type": "tool_search_tool_regex_20251119",
        "name": "tool_search_tool_regex"
      },
      {
        "type": "mcp_toolset",
        "mcp_server_name": "database-server",
        "default_config": {
          "defer_loading": true
        },
        "configs": {
          "search_events": {
            "defer_loading": false
          }
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What events are in my database?"
      }
    ]
  }'

ツール検索の仕組み

クイックスタート

ツール定義

遅延ツール読み込み

レスポンス形式

レスポンスの理解

MCP統合

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

エラー処理

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

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

よくある間違い

400エラー：すべてのツールが遅延されている

400エラー：ツール定義が見つからない

Claudeが期待するツールを見つけられない

プロンプトキャッシング

ストリーミング

バッチリクエスト

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

制限

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

最適化のヒント

使用量