ToolSearch（ツールサーチ）

組み込みツール
ToolSearch
ツールサーチ
MCPツールの定義を起動時に全部読まず、Claudeが実際に必要になったタイミングだけ取り出すために、Claude本人が裏で自動的に呼ぶ内部検索ツール。ユーザーが直接叩くものではなく、ENABLE_TOOL_SEARCHという設定値1つで挙動を切り替える。

MCPサーバーを複数刺してClaude Codeの起動が重くなってきた人向け

MCPサーバーをNotion・Slack・Figma・GitHub・Linearのように複数本刺していて、起動毎にツール定義100個超が読み込まれてClaudeの覚え書きスペースが食い潰されている時に、ENABLE_TOOL_SEARCH=true（Vertex AIや社内プロキシ経由の場合）かデフォルト動作のままで遅延読み込みに切り替え、必要に応じて毎回使うサーバーだけalwaysLoad: trueで前出しする運用に切り替える

ToolSearch は、MCPサーバーを複数刺している時に Claude Code の会話の覚え書きスペース（コンテキスト）を食い潰さないために、内部的に動く検索ツールです。普段は私たちユーザーが直接叩くものではなく、Claude 本人が「今やる作業に必要な MCP ツールを取り出すため」に裏で呼びにいきます。

MCPサーバーを Notion・Slack・Figma・GitHub・Linear と5つ刺すと、何もしてないのに最初から大量のツール定義が読み込まれて重くなる、という昔の挙動を解消するための仕組みです。Claude Code v2 以降はこれがデフォルトでオンになっています。

噛み砕くと「巨大な道具箱を最初に全部広げない」だけの話

会議室に入った瞬間、ホワイトボードに参加者全員の名刺と全資料を一気に貼り出されたら、本題に入る前に視界がノイズで埋まります。ToolSearch がやっているのは、それの逆です。

MCPサーバー1個につき数十個のツールが定義されていることも珍しくなく、5サーバーあれば100個を軽く超えます。これを毎セッションの起動時に Claude の頭の中に全部広げると、肝心の会話が始まる前から記憶の容量が圧迫されます。

そこで Claude Code は「ツールの名前一覧」だけを最初に読み込み、各ツールの説明書きの本文は伏せておきます。Claude が実際に「Notion のページを作りたい」と思った瞬間、はじめて ToolSearch が呼ばれてそのツール定義を取り出す。これが基本動作です。

大事な前提：自分で叩くツールではない

ToolSearch を覚えたら最初に勘違いしやすいのが、「自分で /ToolSearch みたいに呼ぶのかな」というやつ。違います。

これは Claude 本人が自動で呼ぶ内部ツールで、私たちユーザーが触る入口は別にあります。具体的には ENABLE_TOOL_SEARCH という設定値1つと、必要に応じて MCP サーバー側の alwaysLoad 指定。この2つでほぼ全部コントロールできます。

「料理ブログで MCP 5本刺し」を例に、実際の挙動を見る

料理ブログを運営している人を想定します。普段の作業で次の5サーバーを Claude Code に刺している状況です。

  • Notion：レシピの草稿を書く
  • Slack：読者からの DM をチェックする
  • Figma：サムネイル素材を確認する
  • GitHub：ブログテーマファイルを管理する
  • Linear：記事執筆タスクを管理する

ここでは Claude Code v2.1.121 以上を使っていて、Sonnet 4.5 で動かしているという前提です（v2.1.121 未満では alwaysLoad が使えません）。

ステップ1：何も設定せず起動する

普通に claude と叩いてセッションを開きます。Claude Code v2 以降は ToolSearch がデフォルトでオンなので、起動直後の段階では5サーバー分のツール名一覧しか読み込まれていません。中身の説明書きは伏せられています。

$ claude
> こんにちは。今日は何をしますか？

裏側では、Notion の40ツール、Slack の30ツール、Figma の20ツール、GitHub の60ツール、Linear の25ツールの「名前」だけが読まれている、というイメージです。中身の説明書きが全部読まれていたら、ここですでに数万トークンが消えています。

ステップ2：「今日のレシピを Notion に下書きして」と頼む

次のような指示を出します。

> 鶏むね肉のレモン蒸しのレシピ草稿を Notion の「2026年5月レシピ」ページの下に新規ページとして作って。タイトルは「レモン蒸し v1」

このタイミングで Claude が「これは Notion 関連の作業だな」と判断し、内部的に ToolSearch を呼びます。検索結果として Notion サーバーが提供している「ページ作成」「ページ検索」「コメント追加」みたいなツール名から、本当に必要なものだけ、おそらく検索と作成の2つの説明書きが Claude の頭に読み込まれます。

つまり、Slack・Figma・GitHub・Linear の説明書きはこの会話には1文字も入りません。これが「使う分だけ」の意味です。

ステップ3：Slack の DM チェックも頼む

同じセッション内で続けて頼みます。

> ついでに Slack の #reader-dm チャンネルから、今日の DM をまとめて

ここで Claude は再度 ToolSearch を呼び、Slack サーバーから「チャンネルメッセージ取得」系のツール説明書きを追加で読み込みます。Notion 側のツール説明書きは、直前で使ったのですでに頭に残っています。

注意点：ここで初心者がやりがちな勘違いがあります。「ToolSearch のせいで Slack の応答が遅くなった」と感じる人がいますが、遅延の正体は「説明書きを今読み込んでいる時間」です。1回読み込めば、そのセッション中はずっと頭に残るので、2回目以降の Slack 操作は普通に速い。

ステップ4：Slack だけ常時読み込みにする

「読者対応で Slack はほぼ毎セッション使う。毎回の初回呼び出しの一拍が気になる」という運営者なら、Slack だけ常時読み込みに切り替える手があります。Claude Code v2.1.121 以上で使える alwaysLoad 指定を Slack サーバーの設定にだけ付けます。

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-slack"],
      "alwaysLoad": true
    },
    "notion": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-notion"]
    }
  }
}

これで Slack の30ツールは起動時にまとめて読まれ、ToolSearch を経由しなくても最初から見えます。残りの Notion・Figma・GitHub・Linear はこれまで通り遅延読み込み。「毎回必要なやつだけ前に出す」運用です。

ステップ5：Vertex AI と社内プロキシの落とし穴

Vertex AI 経由で動かしている場合、モデルが Sonnet 4.5 / Opus 4.5 以降であっても、ENABLE_TOOL_SEARCH を明示しない限り ToolSearch はデフォルトで無効のままです。社内プロキシ（ANTHROPIC_BASE_URL を自社ホストに向けている場合）も同じです。

ENABLE_TOOL_SEARCH=true を明示した場合、Sonnet 4.5 / Opus 4.5 未満のモデルや tool_reference ブロックを転送できないプロキシではリクエストごと失敗するため、バージョン確認が先決です。Haiku 系は tool_reference ブロック非対応のため、バージョンを問わず動作しません。

ステップ6：閾値モードに切り替える

「全部遅延だと逆に呼び出し待ちが気になる」「もう少し前のめりに読み込んでほしい」という場合、ENABLE_TOOL_SEARCH=auto に切り替えると、ツール定義の合計サイズが Claude の頭の上限の10%以内に収まる時は最初から全部読み込み、はみ出した分だけ遅延読み込みになります。閾値を5%に絞りたければ auto:5 のように数字を指定できます。

つまり ToolSearch は何をしてくれるのか

  • やってくれる：MCP サーバーを5本10本刺しても、Claude の覚え書きスペースを最初から食い潰さない。実際に使ったツールの説明書きだけが、必要になったタイミングで頭に乗る
  • やってくれる：起動時間の体感を軽くする。100超のツール定義を全部読む工程が省かれるため、最初の応答までが速い
  • やってくれない：ツール本体の性能を上げる。あくまで「読み込みのタイミングをずらす」仕組みで、Notion 側の API が遅ければ呼び出し自体は遅いまま
  • やってくれない：Haiku モデルや Vertex AI / 社内プロキシ環境での自動有効化。これらの環境ではデフォルトでオフになる
  • 意味が薄い場面：MCP サーバーを1個しか刺していない、かつそのサーバーのツール数も10個前後しかない場合。元から軽いので遅延読み込みの恩恵がほぼ無い

使いどころ3シナリオ

シナリオ1：MCP を一気に増やして起動が重くなった料理ブログ運営者

Notion・Slack・Figma・GitHub・Linear の5本刺しで、毎セッション起動するたびに最初の応答が来るまで10秒以上待たされていた状況。Claude Code を v2.1 系にアップデートしてデフォルトの ToolSearch を有効のまま使うだけで、起動直後の覚え書きスペース消費が大幅に減ります。読者対応で Slack をほぼ毎回使う運用なら、Slack だけ alwaysLoad: true を付ければ、よく使うやつだけ前に出した最小構成になります。

シナリオ2：Vertex AI 経由で Claude を動かしている社内チーム

会社が Google Cloud 契約で Vertex AI を経由して Claude Sonnet 4.5 を使っている、というケース。Vertex AI ではモデルバージョンに関わらずデフォルトで ToolSearch が無効化されているため、せっかく MCP を刺しても重い挙動のままです。ENABLE_TOOL_SEARCH=true を Claude Code の設定値として明示するだけで、Vertex AI 経由でも遅延読み込みが効きます。ただし対象モデルが Sonnet 4.5 / Opus 4.5 以降であることは別途確認が必要で、未満のモデルで明示有効化するとリクエスト自体が失敗します。

シナリオ3：自社プロキシ経由で Claude API を中継している開発組織

セキュリティ要件で、社内プロキシを通して ANTHROPIC_BASE_URL を独自ホストに向けている組織。この場合も ToolSearch はデフォルトで無効化されます。プロキシ側が tool_reference ブロックを正しく転送できることを確認した上で ENABLE_TOOL_SEARCH=true を立てれば有効化できます。プロキシが転送に対応していないなら、立てた瞬間にリクエストが失敗するので、設定検証は必須です。

初心者が踏みやすい落とし穴

  • Haiku で使おうとして動かない。Haiku 系モデルは tool_reference ブロックに非対応。Sonnet 4 以降か Opus 4 以降を選ぶこと
  • Vertex AI と社内プロキシではモデルバージョンに関わらずデフォルト無効。これらの環境では ENABLE_TOOL_SEARCH=true を明示的にセットしないと有効化されない。逆に、Sonnet 4.5 / Opus 4.5 未満のモデルや tool_reference を転送できないプロキシで無理やり true にすると、リクエストごと失敗する
  • alwaysLoad: true を付けたサーバーは起動がブロックされる。そのサーバーへの接続が成立するまで最大5秒待たされ、MCP_CONNECTION_NONBLOCKING=1 を設定していても効きません。常時読み込みは「本当に毎回使うサーバー」だけに絞るのが安全
  • 個別ツール単位の "anthropic/alwaysLoad": true は _meta の中。トップレベルに書いても効きません。MCP サーバー側のツール定義の _meta オブジェクト内に入れる必要があります
  • ツールの説明文とサーバーの案内文は 2KB で切り詰められる。長すぎる説明書きを書いても、ToolSearch が読む時点で頭が切られます。説明は短く要点を先頭に置く
  • 「ToolSearch」自体を deny で塞ぐと、MCP がほぼ機能停止する。設定で "deny": ["ToolSearch"] を入れると、Claude が遅延読み込み対象のツールに辿り着けなくなります。トラブル切り分け用には便利ですが、本番運用で常時 deny は非推奨
  • 「全部最初から読みたい」なら false。ENABLE_TOOL_SEARCH=false にすると、ToolSearch を経由せず全 MCP ツールを起動時に読み込みます。MCP が1〜2本でツール数も少ない構成ならこの方が動作が分かりやすいです

書き方

（ユーザーが直接叩く構文はなし。Claudeが自動で呼ぶ内部ツール）

設定値で挙動を切り替える:
ENABLE_TOOL_SEARCH=true   # 全MCPツールを遅延読み込み（明示有効化）
ENABLE_TOOL_SEARCH=auto   # 上限の10%以内に収まる時だけ起動時読み込み、超過分は遅延
ENABLE_TOOL_SEARCH=auto:5 # 上記の閾値を5%に変更
ENABLE_TOOL_SEARCH=false  # 遅延せず全部起動時に読み込む
（未設定）                # デフォルトで遅延読み込み、ただしVertex AIと社内プロキシでは無効

やってみるとこうなる

入力

# ユーザーがClaude Codeで料理ブログ用のNotion操作を依頼
> 鶏むね肉のレモン蒸しのレシピ草稿を Notion の「2026年5月レシピ」ページの下に新規ページとして作って

出力例

[内部動作] Claude が ToolSearch を呼び、Notion サーバーから「page.create」「page.search」の2ツール定義のみ読み込み
[Claude 応答]
  Notion で「2026年5月レシピ」を検索しました。
  そのページの子として「レモン蒸し v1」を新規作成します。
  作成完了: https://notion.so/レモン蒸し-v1-xxxxx
  Slack・Figma・GitHub・Linear のツール定義はこの会話では読み込んでいません。

このページに出てきた言葉

MCP
Model Context Protocol の略。Claude のような AI に Notion・Slack・GitHub などの機能を「ツール」として渡すための共通仕様
MCPサーバー
MCP の仕様に沿って動く小さなプログラム。1サーバーが1サービス分のツール群を Claude に提供する
ツール定義
そのツールが何ができて、何を渡すと何を返すかを書いた説明書きの本文。Claude の頭に乗ると会話に使えるスペースを消費する
コンテキスト
Claude が一度の会話で覚えていられる総量の上限。ツール定義・過去会話・指示文を全部足したサイズに上限がある
tool_reference ブロック
ToolSearch を成立させるために Claude API がリクエスト本体に入れる特殊な指定。これに非対応のモデルや中継サーバーでは ToolSearch は動かない
alwaysLoad
MCP サーバーの設定に <code>"alwaysLoad": true</code> と書くと、そのサーバーのツール定義は ToolSearch を経由せず起動時に全部読み込まれる。よく使うサーバーだけ前出ししたい時に使う。Claude Code v2.1.121 以上が必要
Vertex AI
Google Cloud 上で Claude を動かす提供形態の1つ。Anthropic 公式 API ではなく Google 側を経由するため、ToolSearch の有効化条件が独立している

関連項目

公式ドキュメント

https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search

-

← 戻る