Agent SDK のツール検索 ENABLE_TOOL_SEARCH の設定と使い方

接続する MCP サーバーが増えると、ツール定義だけでコンテキストウィンドウの多くを使ってしまいます。Claude Agent SDK のツール検索は、定義を最初から読み込まず、エージェントが必要になったときにカタログを検索して読み込む仕組みで、既定で有効です。このページでは公式の「Scale to many tools with tool search」に沿って、動き方、ENABLE_TOOL_SEARCH の値、query() での指定、見つけやすいツールの書き方、上限を整理します。API で defer_loading を直接書く方法はツール検索ツールで数百のツールを扱うで扱っています。

ツール検索の仕組み

公式はツール検索が解決する課題を2つ挙げています。

コンテキスト効率: ツール定義はコンテキストの大きな割合を占めることがあります（50個のツールで 10〜20K トークン）。
ツール選択の精度: 一度に読み込むツールが 30〜50 個を超えると、選択の精度が落ちます。

有効なときはツール定義がコンテキストから外され、エージェントには利用できるツールの要約が渡されます。まだ読み込まれていない機能が必要になると検索し、関連の高いツールが既定で最大5個読み込まれます。読み込まれたツールは以後のターンでも使えますが、それを見つけたメッセージが SDK の圧縮（compaction）で畳まれると外れ、次に必要になったときに検索し直します。

検索のたびに往復が1回増えますが、ツールが多ければ毎ターンのコンテキストが小さくなることで相殺されます。逆に、ツールが10個程度より少なく定義がコンテキストに十分収まるなら、最初から全部読み込むほうが通常は高速です。

ENABLE_TOOL_SEARCH の設定

ツール定義を後回しにするかどうかは環境変数 ENABLE_TOOL_SEARCH で決めます。

値	動作
（未設定）	有効。定義は後回しにされ、必要時に検索される。Opus 4 / Sonnet 4 より前のモデル、Google Cloud Agent Platform の古いモデル、Azure 上の Microsoft Foundry デプロイでは最初から全部読み込む
`true`	有効。未設定と同じフォールバックが働く
`auto`	後回しにできる定義の合計がモデルのコンテキストウィンドウの 10% に達するまでは無効で、達すると有効になる。同じ会話では、後で 10% を下回っても有効のままのことがある
`auto:N`	`auto` の割合を変える。`auto:5` なら 5% で有効になり、値が小さいほど早く有効になる
`false`	無効。すべての定義が毎ターン読み込まれる

対象は、リモート MCP サーバーのツールも SDK の MCP サーバーで作ったカスタムツールも含む、登録済みの全ツールです。auto のしきい値には、alwaysLoad を付けていない MCP ツール（どのサーバーのものでも合算）と、必要時に読み込まれる組み込みツールが数えられます。Bash・Read・Edit などの中核の組み込みツールは最初から読み込まれ、数えられません。

設定で変えられない場合

Azure 上の Microsoft Foundry: デプロイ側がサーバーで拒否するため、SDK が検知して最初から読み込みます。ENABLE_TOOL_SEARCH では上書きできません。
未対応モデル: SDK の未対応モデル一覧にあるモデルでは、どの値でも最初から読み込みます。
Google Cloud Agent Platform: Claude Opus 4.5・Sonnet 4.5・Haiku 4.5 以降は既定で有効です。それより古いモデルは必要なベータヘッダーを受け付けないため最初から読み込み、上書きできません。
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: これを設定すると無効のままで、ENABLE_TOOL_SEARCH では戻せません。Claude Code v2.1.227 以降は、組織が managed settings でこの変数のもとでも有効に保てます。
HIPAA 構成のセッション: 無効で、ENABLE_TOOL_SEARCH でも managed settings でも有効にできません。

ANTHROPIC_BASE_URL のゲートウェイ経由でも既定で有効です（v2.1.304 より前は明示の設定が必要でした）。ゲートウェイが拒否する場合の対処は、公式の「Tool search through an LLM gateway」を参照してください。

query() での指定例

値は query() の env オプションで渡します。TypeScript の env はサブプロセスの環境を置き換えるので ...process.env で引き継ぎ、Python の env は継承した環境の上に重ねられます。次の例は、多数のツールを持つリモート MCP サーバーに接続し、ワイルドカードで全ツールを事前承認して、後回しにできる定義が 5% に達したら検索を有効にします。

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

try {
  for await (const message of query({
    prompt: "Find and run the appropriate database query",
    options: {
      mcpServers: {
        "enterprise-tools": {
          type: "http",
          url: "https://tools.example.com/mcp"
        }
      },
      allowedTools: ["mcp__enterprise-tools__*"],
      env: {
        ...process.env,
        ENABLE_TOOL_SEARCH: "auto:5"
      }
    }
  })) {
    if (message.type === "result" && message.subtype === "success") {
      console.log(message.result);
    }
  }
} catch (error) {
  console.log(`Session ended with an error: ${error}`);
}

options = ClaudeAgentOptions(
    mcp_servers={
        "enterprise-tools": {
            "type": "http",
            "url": "https://tools.example.com/mcp",
        }
    },
    allowed_tools=["mcp__enterprise-tools__*"],
    env={"ENABLE_TOOL_SEARCH": "auto:5"},
)

URL は自分の MCP サーバーのものに置き換えます。単発の query() はエラーの結果を流した後に例外を送出するので、例では全体を try で囲んでいます。失敗の理由はループ内で結果メッセージの subtype（error_during_execution など）を見ると分かります。接続方法は Agent SDK で MCP サーバーに接続するを参照してください。

検索の対象から外す

毎ターン必要な少数のツールは、MCP サーバーの設定に alwaysLoad: true を付けると ENABLE_TOOL_SEARCH の値にかかわらず最初から読み込まれます。読み込んだ分だけコンテキストを使うので、絞って使います。また、このとき起動時に標準の5秒の接続タイムアウトを上限としてそのサーバーのツールを待ちます。逆に alwaysLoad: false を付けると、サーバー作者が最初から読み込むよう指定したツールも含めて全部を検索の対象にします（Claude Code v2.1.287 以降）。

見つけやすいツールにする

検索はツール名と説明文に対してクエリを照合します。名前と説明文の書き方で、見つかりやすさが変わります。

対象	見つかりやすい	見つかりにくい
ツール名	`search_slack_messages`	`query_slack`
説明文	Search Slack messages by keyword, channel, or date range	Query Slack

システムプロンプトに、利用できるツールの分類を書き足す方法もあります。何を検索できるかをエージェントが把握できます。claude_code プリセットに append を付けると、プリセットのプロンプトを置き換えずに追記できます（Python では system_prompt に同じ内容の辞書を渡します）。

options: {
  systemPrompt: {
    type: "preset",
    preset: "claude_code",
    append: "You can search for tools to interact with Slack, GitHub, and Jira."
  }
}

システムプロンプトの指定方法全体は Agent SDK のシステムプロンプト変更にまとめています。

上限と対応モデル

ツール数の上限: カタログに 10,000 個まで
検索結果: 1回の検索で、関連の高いツールを既定で最大5個返す
対応モデル: Opus 4・Sonnet 4・Haiku 4.5 以降。Google Cloud Agent Platform では Opus 4.5・Sonnet 4.5・Haiku 4.5 以降。それより前のモデルでは定義を最初から読み込む

Claude Code 本体でも同じ環境変数で動作を変えられ、ENABLE_TOOL_SEARCH=auto:5 claude のように起動します。読み込みの状態は /context の表示で確認でき、しきい値を下回っているのに (deferred) や (loaded on-demand) と出るのは、その会話で一度有効になった検索が続いている状態で、対応は不要です。

本ページは Scale to many tools with tool search を中心に、Claude Code の MCP ドキュメント（Scale with MCP tool search の節）と Tool search tool を照合した非公式の日本語解説です（確認日 2026-11-06）。最新の仕様は公式ドキュメントを確認してください。