多くのツールにスケーリングするツール検索

必要なものだけをオンデマンドで検出して読み込むことで、エージェントを数千のツールにスケーリングします。

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

このアプローチは、ツールライブラリがスケーリングするにつれて、2 つの課題を解決します。

• コンテキスト効率： ツール定義はコンテキストウィンドウの大部分を消費する可能性があります（50 個のツールは 10～20K トークンを使用できます）。実際の作業用のスペースが減少します。
• ツール選択精度： 30～50 個以上のツールが一度に読み込まれると、ツール選択精度が低下します。

ツール検索はデフォルトで有効になっています。このページでは、仕組み、設定方法、およびツール検出の最適化方法について説明します。

ツール検索の仕組み

ツール検索がアクティブな場合、ツール定義はコンテキストウィンドウから保留されます。エージェントは利用可能なツールの概要を受け取り、タスクが既に読み込まれていない機能を必要とする場合、関連するツールを検索します。最も関連性の高い 3～5 個のツールがコンテキストに読み込まれ、その後のターンで利用可能なままになります。会話が十分に長く、SDK が以前のメッセージをコンパクト化してスペースを解放する場合、以前に検出されたツールが削除される可能性があり、エージェントは必要に応じて再度検索します。

ツール検索は、Claude が初めてツールを検出するときに 1 つの追加ラウンドトリップを追加します（検索ステップ）。ただし、大規模なツールセットの場合、これはすべてのターンでより小さいコンテキストによってオフセットされます。ツールが約 10 個未満の場合、すべてを事前に読み込む方が通常は高速です。

基盤となる API メカニズムの詳細については、API のツール検索を参照してください。

ツール検索を設定する

ツール検索はデフォルトでオンです。Vertex AI ではデフォルトで無効になっており、Claude Sonnet 4.5 以降および Claude Opus 4.5 以降でサポートされています。また、ANTHROPIC_BASE_URL が非ファーストパーティホストを指す場合も無効になります。ほとんどのプロキシは tool_reference ブロックを転送しないためです。ENABLE_TOOL_SEARCH 環境変数でいずれかのデフォルトをオーバーライドできます。

ツール検索は、リモート MCP サーバーから来るか、カスタム SDK MCP サーバーから来るかに関わらず、すべての登録ツールに適用されます。auto を使用する場合、閾値はすべてのサーバー全体のすべてのツール定義の合計サイズに基づいています。

query() の env オプションで値を設定します。この例は、多くのツールを公開するリモート MCP サーバーに接続し、ワイルドカードですべてのツールを事前承認し、auto:5 を使用して、ツール定義がコンテキストウィンドウの 5% を超える場合にツール検索をアクティブにします。

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Find and run the appropriate database query",
options: {
mcpServers: {
"enterprise-tools": {
// Connect to a remote MCP server
type: "http",
url: "https://tools.example.com/mcp"
}
},
allowedTools: ["mcp__enterprise-tools__*"], // Wildcard pre-approves all tools from this server
env: {
ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when tools exceed 5% of context
}
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
options = ClaudeAgentOptions(
mcp_servers={
"enterprise-tools": {
"type": "http",
"url": "https://tools.example.com/mcp",
}
},
allowed_tools=[
"mcp__enterprise-tools__*"
],  # Wildcard pre-approves all tools from this server
env={
"ENABLE_TOOL_SEARCH": "auto:5"  # Activate tool search when tools exceed 5% of context
},
)

async for message in query(
prompt="Find and run the appropriate database query",
options=options,
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)


asyncio.run(main())

ENABLE_TOOL_SEARCH を "false" に設定すると、ツール検索が無効になり、すべてのツール定義がすべてのターンでコンテキストに読み込まれます。これにより検索ラウンドトリップが削除されます。ツールセットが小さい（約 10 個未満のツール）場合、定義がコンテキストウィンドウに快適に収まる場合は、より高速になる可能性があります。

ツール検出を最適化する

検索メカニズムは、ツール名と説明に対してクエリを照合します。search_slack_messages のような名前は、query_slack よりも広い範囲のリクエストに対して表示されます。「キーワード、チャネル、または日付範囲で Slack メッセージを検索」などの具体的なキーワードを含む説明は、「Slack をクエリ」などの一般的な説明よりも多くのクエリに一致します。

利用可能なツールカテゴリをリストするシステムプロンプトセクションを追加することもできます。これにより、エージェントは検索対象のツールの種類に関するコンテキストを取得します。

You can search for tools to interact with Slack, GitHub, and Jira.

制限

• 最大ツール数： カタログ内の 10,000 個のツール
• 検索結果： 検索ごとに最も関連性の高い 3～5 個のツールを返します
• モデルサポート： Haiku を除くすべての Claude モデル

関連ドキュメント

• API のツール検索：カスタム実装を含むツール検索の完全な API ドキュメント
• MCP サーバーを接続する：MCP サーバー経由で外部ツールに接続する
• カスタムツール：SDK MCP サーバーで独自のツールを構築する
• TypeScript SDK リファレンス：完全な API リファレンス
• Python SDK リファレンス：完全な API リファレンス