ツール検索ツール
ツール検索ツールにより、Claudeは数百または数千のツールを動的に検出して読み込むことで、これらのツールを効率的に操作できます。すべてのツール定義をあらかじめコンテキストウィンドウに読み込む代わりに、Claudeはツールカタログ（ツール名、説明、引数名、引数説明を含む）を検索し、必要なツールのみを読み込みます。
このアプローチは、ツールライブラリが拡大する際の2つの重大な課題を解決します。
- コンテキスト効率: ツール定義は、コンテキストウィンドウの大部分を消費する可能性があります（50個のツール ≈ 10-20Kトークン）。これにより、実際の作業用のスペースが減少します
- ツール選択精度: Claudeのツール選択能力は、従来利用可能な30～50個を超えるツールでは大幅に低下します
これはサーバー側のツールとして提供されていますが、独自のクライアント側ツール検索機能を実装することもできます。詳細については、カスタムツール検索実装を参照してください。
ツール検索ツールは現在パブリックベータ版です。
この機能を使用するには、"advanced-tool-use-2025-11-20" ベータヘッダーをAPIリクエストに追加してください。
ツール検索ツールの使用経験を共有するには、フィードバックフォームからお問い合わせください。
プラットフォームとモデルのサポート
| プラットフォーム | サポートされているモデル |
|---|---|
| Claude API | Claude Opus 4.5、Claude Sonnet 4.5 |
| Microsoft Foundry | Claude Opus 4.5、Claude Sonnet 4.5 |
| Google Cloud Vertex AI | Claude Opus 4.5、Claude Sonnet 4.5 |
| Amazon Bedrock | Claude Opus 4.5 |
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は検出されたツールから選択して、それらを呼び出します
これにより、コンテキストウィンドウを効率的に保ちながら、高いツール選択精度を維持できます。
クイックスタート
遅延ツールを使用した簡単な例を次に示します。
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: advanced-tool-use-2025-11-20" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-4-5-20250929",
"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
}
]
}'ツール定義
ツール検索ツールには2つのバリアントがあります。
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
}{
"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を追加することで、ツールをオンデマンド読み込み用にマークします。
{
"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がツール検索ツールを使用する場合、レスポンスには新しいブロックタイプが含まれます。
{
"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_result",
"tool_use_id": "srvtoolu_01ABC123",
"content": [{ "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_resultwithtool_reference: 検出されたツールへの参照を含む検索結果tool_use: Claudeが検出されたツールを呼び出しています
tool_referenceブロックは、Claudeに表示される前に自動的に完全なツール定義に展開されます。この展開を自分で処理する必要はありません。toolsパラメータにすべての一致するツール定義を提供する限り、APIで自動的に発生します。
MCP統合
ツール検索ツールはMCPサーバーと連携します。"mcp-client-2025-11-20" ベータヘッダーをAPIリクエストに追加してから、mcp_tool_setをdefault_configsと共に使用してMCPツールの読み込みを遅延させます。
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: advanced-tool-use-2025-11-20,mcp-client-2025-11-20" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-4-5-20250929",
"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_tool_set",
"mcp_server_name": "database-server",
"default_configs": {
"defer_loading": true
},
"configs": {
"search_events": {
"defer_loading": false
}
}
}
],
"messages": [
{
"role": "user",
"content": "What events are in my database?"
}
]
}'MCP設定オプション：
default_configs.defer_loading: MCPサーバーからのすべてのツールのデフォルトを設定しますconfigs: 名前で特定のツールのデフォルトをオーバーライドします- 複数のMCPサーバーをツール検索と組み合わせて、大規模なツールライブラリを実現します
カスタムツール検索実装
カスタムツール（例：埋め込みやセマンティック検索を使用）からtool_referenceブロックを返すことで、独自のツール検索ロジックを実装できます。
{
"type": "tool_result",
"tool_use_id": "toolu_custom_search",
"content": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}参照されるすべてのツールは、トップレベルのtoolsパラメータにdefer_loading: trueを指定した対応するツール定義を持つ必要があります。このアプローチにより、ツール検索システムとの互換性を維持しながら、より高度な検索アルゴリズムを使用できます。
埋め込みを使用した完全な例については、埋め込みを使用したツール検索クックブックを参照してください。
エラーハンドリング
ツール検索ツールはツール使用例と互換性がありません。 ツール使用の例を提供する必要がある場合は、ツール検索なしの標準ツール呼び出しを使用してください。
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: ツール検索サービスが一時的に利用できません
一般的な間違い
プロンプトキャッシング
ツール検索はプロンプトキャッシングと連携します。マルチターン会話を最適化するためにcache_controlブレークポイントを追加します。
import anthropic
client = anthropic.Anthropic()
# ツール検索を使用した最初のリクエスト
messages = [
{
"role": "user",
"content": "What's the weather in Seattle?"
}
]
response1 = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
betas=["advanced-tool-use-2025-11-20"],
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.beta.messages.create(
model="claude-sonnet-4-5-20250929",
betas=["advanced-tool-use-2025-11-20"],
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_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "tool_reference", "tool_name": "get_weather"}]}}
// Claudeが検出されたツールで続行しますバッチリクエスト
メッセージバッチAPIにツール検索ツールを含めることができます。メッセージバッチAPIを通じたツール検索操作は、通常のメッセージ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": {
"input_tokens": 1024,
"output_tokens": 256,
"server_tool_use": {
"tool_search_requests": 2
}
}
}現在の価格情報については、価格ページを参照してください。