MCPのツール定義はなぜコンテキストを圧迫するのか — Tool Searchが必要になった理由

Tool Search Toolは、MCPなどのツール定義を最初から全部読み込まず、Claudeが必要になったときに検索して取り込む仕組みです。5サーバー構成で約55,000トークンかかる初期消費を、実際に使うツールの分だけに抑えます。Claude Codeでは既定で有効で、ENABLE_TOOL_SEARCHで挙動を切り替えます。

この記事は、MCPのツール定義がコンテキストを圧迫する仕組みとTool SearchのAPI側の数値を扱います。Claude CodeでのalwaysLoadやENABLE_TOOL_SEARCHの設定手順はMCPのトークンオーバーヘッドを抑える設定にあります。

MCPサーバーを増やすと何が起きるか

MCPサーバーを1つ繋ぐたびに、そのサーバーが持つツールの定義(名前・説明文・引数のスキーマ)がまるごとClaudeのコンテキストに送られます。GitHub・Slack・Sentry・Grafana・Splunkという典型的な5サーバー構成では、Claudeが作業を始める前の時点で、ツール定義だけに約55,000トークンが消えます。

ツール定義は毎回のリクエストに含まれる入力トークンです。会話が何ターン続いても、繋いだサーバーの数に応じた固定コストが毎回積み上がります。プロンプトキャッシュが効けば単価は下がりますが、コンテキストウィンドウという有限の枠を使っていることは変わりません。

ツールが増えると、量と精度の2つが別々に悪化する

問題は2つあり、原因が違います。

どちらか一方の指標だけを見ていると、もう一方の劣化を見逃します。数百のツールを一度に並べる構成は、両方を同時に踏みます。

Tool Searchを検討する目安として、公式は次の条件を挙げています。左のどれかに当てはまれば導入を考える対象で、右に当てはまるなら標準のツール呼び出しで足ります。

ツール構成を変えるとプロンプトキャッシュはどうなるか

Claude Codeはリクエストのたびに会話履歴を送っており、通常はプロンプトキャッシュで同じ内容を安い読み取り単価で再処理します。ツール定義が変わるとこのキャッシュが外れることがあり、Claude Codeのコスト表示はそれを名指しします。セッションのコスト表示にあるPrompt cache (main)行のMisses欄に、原因を推定できたときはlikely cause: tool definitions changedと出ます。この原因表示はv2.1.260以降の機能です。

遅延ロードしたツールについては、API側の仕様がはっきりしています。遅延対象のツールは、システムプロンプトの接頭辞(プレフィックス)から除かれます。Claudeが検索でツールを見つけると、会話の途中にtool_referenceブロックが追加され、完全な定義に展開されてからClaudeに渡ります。接頭辞は変わらないので、プロンプトキャッシュは保たれます。

守る点が1つあります。defer_loading: trueを付けたツールにcache_controlを付けると、APIは400を返します。キャッシュのブレークポイントは、遅延させないツール側に置きます。

もう1つ、Tool Search Toolを含む全ツールにdefer_loading: trueを付けた場合も400になります。サーバー側のツール変更で一覧が揺れるのを防ぎたいときは、MCPコネクタのmcp_tool_listingでツール一覧を固定する手順が参考になります。

Tool Searchは2つの問題をどう解決するか

遅延させたツールも、定義そのものは毎回のリクエストのtools配列に全部入れて送ります。APIはサーバー側で検索を実行し、tool_referenceブロックを展開するために、遅延ツールを含む全定義を必要とするためです。減るのは、コンテキストに入る分であって、送信する内容ではありません。

Tool Search Tool自身は即時ロードし(ここにdefer_loadingは付けません)、遅延させたいツールにdefer_loading: trueを付けます。Claude Codeでは、ツール名とサーバーの説明文だけがセッション開始時にロードされます。

Amazon Bedrockでは、サーバー側のTool SearchはInvokeModel APIだけで使え、Converse APIでは使えません。

検索方式はtool_search_tool_regex_20251119(regex版)とtool_search_tool_bm25_20251119(BM25版)の2種類です。1回の検索で返る件数は、Claudeが検索入力のlimitで1〜10,000件の範囲に変えられます。パターンの長さはregex版で200文字、BM25版のクエリで500文字までです。

対応モデルはFable 5.1・Mythos 5.1・Opus 5.5・Sonnet 5.5・Opus 4.8などで、tool_referenceブロックを扱える世代に限られます。候補を絞ってから渡すので、母集団が数千に増えても、Claudeが見るのはヒットした少数の定義です。

Claude Codeの既定とAPI直接利用の既定は逆

Claude Codeでも、次の場合はTool Searchが無効になり、全ツールが起動時に読み込まれます。

• ANTHROPIC_BASE_URLがAnthropic以外のホスト(LLMゲートウェイやプロキシなど)を指しているとき(ENABLE_TOOL_SEARCHを明示すれば上書きできます)
• 4.5世代より前のモデルをAgent Platformで使うとき
• AzureでホストしたMicrosoft Foundryのデプロイメント(サーバー側が拒否するため、ENABLE_TOOL_SEARCHでも上書きできません)
• CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASを設定しているとき(ENABLE_TOOL_SEARCHでは戻せません。v2.1.227以降は、組織が管理設定でTool Searchを維持することもできます)

API側のコネクタでサーバー単位に遅延させる設定は、次のように書きます。default_configで全ツールを遅延対象にし、configsで個別のツールだけ設定を変えます。

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": { "defer_loading": true },
  "configs": { "search_events": { "enabled": false } }
}

この例ではsearch_eventsが無効になり、残りのツールはすべて有効かつ遅延ロードです。

検索で見つけてもらえるかは、ツール名と説明文で決まる

Tool Searchの精度は、検索アルゴリズムだけでなく、検索される側の書き方にも左右されます。サーバーの説明文(server instructions)は、Skillsと同じように、Claudeがいつそのサーバーのツールを検索するかを判断する材料になります。扱うタスクの種類、検索すべき場面、主要な機能を書いておきます。

Claude Codeは、長すぎる説明文を途中で切り詰めます。上限は、サーバーのinstructionsと起動時に読み込まれるツールの説明文が4,096文字です。Tool Search経由で読み込むツールの説明文は16,384文字です。

ただし検索がクエリと照合するのは、短いほうの上限に収まる範囲だけです。重要な内容と、Claudeが検索に使いそうな語は冒頭に置きます。v2.1.296より前は、短いほうの上限が2,048文字でした。

API側のドキュメントは、ほかにも次の工夫を挙げています。

• ツール名をgithub_やslack_のようにサービスや用途で接頭辞にそろえる。1回の検索で同じグループがまとめて当たります
• 説明文に、利用者がタスクを言い表す言葉を入れる
• システムプロンプトに「SlackやGitHub、Jiraを操作するツールを検索できる」のような一節を足す

ただし、説明文を磨いても、ツールの絶対数が閾値を超えたときの選択精度の劣化は消えません。説明文は検索の当たりやすさの軸で、30〜50個の壁とは別の軸です。

手元のClaude Codeで読み込むサーバーを絞る

CIやバックグラウンドセッションのように、読み込むサーバー自体を絞りたい場合は、--mcp-configと--strict-mcp-configが使えます。v2.1.287のclaude --helpには次のように出ます。

claude --version
# 2.1.287 (Claude Code)
 
claude --help
#   --mcp-config <configs...>   Load MCP servers from JSON files or
#                               strings (space-separated)
#   --strict-mcp-config         Only use MCP servers from --mcp-config,
#                               ignoring all other MCP configurations

--strict-mcp-configを付けると、--mcp-configで渡したサーバーだけが読み込まれ、ほかの設定にあるサーバーは無視されます。2つのフラグの使い分けはClaude Codeの--mcp-configと--strict-mcp-configの使い分けにあります。

regex版とBM25版でクエリの書き方がどう変わるかはTool Search Toolのregex版とBM25版の違いが、ENABLE_TOOL_SEARCHの値ごとの挙動はAgent SDK Tool Searchの使い方が扱っています。

全部をTool Search任せにしない判断

Tool Searchは万能ではありません。前掲の早見表のとおり、ツールが10個未満で全部が毎回使われる構成では、検索の1ステップが余計に挟まるぶん遠回りです。

頻繁に使うツールの扱いは、APIとClaude Codeで単位が違います。

alwaysLoadを付けたサーバーは、起動時にツールの到着を待つため、起動が最大5秒(標準の接続タイムアウト)遅れることがあります。有効なcachedエントリを持つリモートサーバーは、接続せずにキャッシュからツールを供給するので、起動を待たせません。

Claude CodeのENABLE_TOOL_SEARCHは、全部を遅延させる以外の値も取れます。

ENABLE_TOOL_SEARCH=auto:5 claudeのように起動時に付けるか、settings.jsonのenvに書きます。

もう1つの選択肢は、MCPサーバーを増やさないことです。コスト削減ガイドは、gh・aws・gcloud・sentry-cliのようなCLIは、ツールごとの一覧をコンテキストに足さないので、MCPサーバーより効率的としています。CLIで済む作業を、わざわざMCPサーバー経由にする理由はありません。

まとめ

MCPサーバーを足すと、トークン消費とツール選択精度の2つのコストを同時に負います。Tool Searchはその両方を軽くしますが、毎ターン使うツールを遅延させない、サーバーの説明文を検索に当たる形で書く、CLIで済むならサーバーを足さない、という判断は設計する側に残ります。