この記事の要点: Claude Code には、MCPツールのスキーマ定義を「使う直前」までロードしない deferred tools（遅延ツール）という仕組みと、それを検索・ロードする組み込みツール ToolSearch がある。私は2026年7月8日にこの挙動を実測し、翌7月9日に公式ドキュメント4ページと突き合わせた。本記事で扱う4つの挙動——①クエリ形式は3種類ある、②エラー「No matching deferred tools found」はツールの不存在とMCPサーバー未接続を区別しない、③サーバー切断でロード済みツールも「no longer available」になる、④ロードは1回の ToolSearch 呼び出しにまとめるべき——は、2026-07-09時点の調査ではいずれも公式ドキュメントページに記述がなかった。実測ログと GitHub Issue・Anthropic製MCPサーバーの instructions テキストを根拠に、仕組みと運用上の設計指針を解説する。
ToolSearchとは——ツール定義を「使う直前」まで読ませない仕組み
MCPサーバーをまだ1つも繋いでいない（あるいは1つしか繋いでいない）人には、現時点で実害のない話に見えるかもしれない。だがこれは複数のサーバーを繋いだ瞬間に効いてくる仕組みであり、繋ぐ前に知っておくと「どのサーバーを常時接続にするか」という設計判断そのものが変わる。実際、私はこの仕組みを理解しないまま ToolSearch のエラーに遭遇し、意味を誤読しかけた（後述）。
背景にある問題はシンプルだ。MCPサーバーを複数接続すると、全ツールのスキーマ定義（引数・説明文）がシステムプロンプトに常駐し、コンテキストを圧迫する。ツールを1回も使わないセッションでも、定義文はずっとそこに居座り続ける。
ToolSearch はこれを「ツール名だけ先に見せて、スキーマ本体は使う直前にロードする」という設計で解決する。スキーマ未ロードのツールは deferred tools（遅延ツール）と呼ばれるリストに名前だけ載っており、Claude が必要になったタイミングで ToolSearch を呼んで検索・ロードする。
公式ドキュメントの Tools reference にも ToolSearch は載っている。ただし説明は「Searches for and loads deferred tools when tool search is enabled（ツール検索が有効な場合に deferred tools を検索してロードする）」という趣旨の1行だけだ。ここから先——クエリの書き方、エラーの読み方、サーバー切断時の挙動——は、2026-07-09時点の調査では公式ドキュメントに書かれていない。以下、実測で確かめた4つの挙動を順に見ていく。
挙動① クエリ形式は3種類ある
ToolSearch のクエリには3つの形式がある。
| 形式 | 書き方 | 用途 |
|---|---|---|
select: 完全指定 |
select:ツール名1,ツール名2 |
ツール名が分かっている場合。カンマ区切りで複数指定できる |
| キーワード検索 | 検索語 |
ツール名が分からない場合の探索 |
+ 必須語指定 |
+キーワード |
必須語を指定した絞り込み |
ToolSearch を直接呼ぶのは Claude 自身だが、ユーザー側から「ToolSearch で select:mcp__claude-in-chrome__tabs_context_mcp をロードして」のように頼めば、意図した形式で呼ばせられる（MCPツールの内部名は、この例のように mcp__サーバー名__ツール名 の形式になっている）。スキルやサブエージェント向けの指示書にロードすべきツールを書いておく場合も、この書式で指定することになる。
この書式定義は、2026-07-09時点の調査では公式ドキュメントページのどこにも見当たらなかった。Anthropic の API 仕様書（Platform ドキュメント）には正規表現版と自然言語検索版という2種類のクエリ形式を持つ tool search 機能が定義されているが、これは API 汎用機能の仕様であり、Claude Code 内蔵の ToolSearch が受け付ける select: 構文とは階層が異なる。
select: 構文の来歴について手がかりになるのは GitHub Issue #31002（コミュニティ報告、Anthropic 公式の言明ではない）だ。報告者の独自調査によれば select: 構文は v2.1.31 で追加されたとされ、報告者自身が「the change was not documented in the release notes or anywhere else we could find（この変更は release notes にも、我々が探せたどこにも文書化されていなかった）」と明言している。
挙動② 「No matching deferred tools found」はツールの不存在を意味しない
この仕組みは、正直なところ知らなくても普段は使える。ToolSearch は Claude が自動で呼ぶため、ユーザーが意識する場面は少ない。問題は、エラーが出た瞬間に切り分けができなくなることだ。
2026年7月8日、私は MCP サーバーが無効な状態で select: 指定の ToolSearch を実行させた。返ってきたのは次のメッセージだった。
No matching deferred tools found
この文言だけでは、次の2つが区別できない。
- (a) ツール自体が存在しない（ツール名の打ち間違い、そもそもそのサーバーにないツール）
- (b) MCPサーバーが接続されていないだけ（ツールは実在するが、deferred リストに載っていない）
私は最初これを (a) と誤読しかけた。実際には (b) で、/mcp コマンドでサーバーを有効化すると、そのサーバーのツールが deferred リストに登場し、ToolSearch でロードした後は通常のツールと同様に呼び出せた。ツールは最初から実在していたのだ。
この曖昧さから得られる設計上の教訓は明確で、スキルやサブエージェント向けの指示を書くときは、フォールバック手順を明記する必要があるということだ。ToolSearch のエラーメッセージだけでは原因の切り分けができないため、指示を受けた側が「ツールがない」と誤断してタスクを放棄しかねない。私は指示書に次のような一節を入れるようにしている。
## ツールが見つからない場合のフォールバック
- ToolSearch が「No matching deferred tools found」を返しても、ツールが存在しないと断定しない
- まず MCP サーバーの接続状態を疑い、`/mcp` で対象サーバーが接続済みかを確認する
（未接続ならユーザーに接続を案内する）
- 接続済みなのに見つからない場合に限り、ツール名の誤りを疑う
このエラーメッセージ自体も、2026-07-09時点の調査では公式ドキュメントに登場しない。API 仕様書に「該当なしの検索はエラーではなく空の結果を返す」という近縁の記述があるだけで、Claude Code の CLI 上で表示されるこの文言と、その切り分け方法は書かれていなかった。
挙動③ サーバー切断でロード済みツールも「no longer available」になる
ToolSearch でロードしたツールは、ロード後も MCP サーバーの接続に依存し続ける。サーバーが切断されると、一度ロード済みのツールも「no longer available」という状態になり、使えなくなる。
この挙動は GitHub Issue #38043（コミュニティのバグ報告）に、Claude Code が実際に出すシステムメッセージの原文として引用されている。
The following deferred tools are no longer available (their MCP server disconnected). Do not search for them — ToolSearch will return no match
（これらの deferred tools はもう利用できない（MCPサーバーが切断された）。検索してはならない——ToolSearch は該当なしを返す）
私が2026年7月8日に観測した挙動も、この文言と整合する。
では、サーバーが再接続されたらツールは復帰するのか。ここは報告が割れている。私の環境では2026年7月8日の時点で、再接続によってツールは復帰した。一方、同じ Issue #38043 には「再接続後もツールはセッションから除去されたままで、リカバリはセッションの再起動しかない」という逆の報告がある。なおこの Issue は「duplicate」ラベルで既にクローズされており、Anthropic 公式スタッフの返信は確認できていない、あくまで1ユーザーの報告である点も留保として押さえておきたい。どちらも Anthropic 公式の言明ではなく、バージョンや接続方式による差異の可能性もある。現時点では、切断からの自動復帰を前提に運用を設計しないほうが安全というのが私の判断だ。
なお、公式ドキュメントには MCP サーバーの自動再接続の仕様（HTTP / SSE サーバーは1秒から始めて間隔を倍々にしながら最大5回再試行する、stdio サーバーは自動再接続しない）は記載されている。しかしその間、ロード済みの deferred tools がどう扱われるか——保持されるのか、無効化されるのか——は、2026-07-09時点の調査では書かれていなかった。
挙動④ ロードは1回のToolSearchにまとめる
必要なツールが複数あるとき、1ツールずつ ToolSearch を呼ぶのは無駄が大きい。1回の呼び出しごとにラウンドトリップ（往復のやりとり）が発生するためだ。select: クエリはカンマ区切りの複数指定を受け付けるので、必要なツールは1回の ToolSearch 呼び出しにまとめてロードするのが原則になる。
この原則の一次ソースは、公式ドキュメントページではなく、Anthropic 製 MCP サーバーの instructions テキスト（サーバー接続時にセッションへ注入される、サーバー自身の使い方指示）だ。computer-use サーバーの instructions には次のように明記されている。
Loading via ToolSearch — load in bulk, not one-by-one: if computer-use tools are in the deferred list, load them ALL in a single ToolSearch call（中略）Don't use
select:for individual tools — that's one round-trip per tool.
（ToolSearch でのロードは一括で。1つずつではなく：computer-use のツールが deferred リストにあるなら、1回の ToolSearch 呼び出しで全部ロードすること。select: を個別ツールに使ってはならない——それはツール1つにつき1往復かかる）
claude-in-chrome サーバーの instructions にも同趣旨の文言が別途ある。
batch every tool you expect to need into ONE ToolSearch call (the select query accepts a comma-separated list). Do NOT load tools one at a time; each separate ToolSearch call wastes a full round-trip.
（必要になりそうなツールは1回の ToolSearch 呼び出しにまとめること（select クエリはカンマ区切りリストを受け付ける）。ツールを1つずつロードしてはならない。ToolSearch 呼び出しを分けるたびに丸ごと1往復が無駄になる）
これらの instructions は、該当 MCP サーバーに接続した通常のセッションでシステムリマインダーとして自動的に注入される情報であり、特別な手段で抜き出したものではない。
一括ロードが単一サーバーの都合ではなく、確認できた computer-use / claude-in-chrome の2サーバーいずれにも共通する運用指示であることが分かる（他の Anthropic 製 MCP サーバーまで悉皆調査したわけではない）。自作の MCP サーバーやスキルの指示書を書く人は、同じ原則を自分の instructions にも書いておく価値がある。
一方、公式ドキュメントページ側には「頻繁に使う3〜5個のツールは非遅延（最初からロード済み）にしておく」という近縁の最適化助言があるだけで、「1回にまとめよ」という直接的な推奨は2026-07-09時点の調査では見当たらなかった。
補足として、ToolSearch によるロードはサブエージェント（Taskツールで起動する子エージェント）からも機能する。私は2026年5月30日に、サブエージェントから claude-in-chrome のタブ取得ツール（mcp__claude-in-chrome__tabs_context_mcp）を ToolSearch でロードして呼び出せることを確認している。
「公式ドキュメントを読めばいいのでは」への答え
ここまで読んで「公式ドキュメントを読めば済む話では？」と思った人のために、突き合わせの結果をまとめておく。私は2026年7月9日に、次の4ページを対象に裏取り調査を行った。
- Claude Code ドキュメント「Connect Claude Code to tools via MCP」（code.claude.com/docs/en/mcp）
- Claude Code ドキュメント「Scale to many tools with tool search」（code.claude.com/docs/en/agent-sdk/tool-search）
- Claude Code ドキュメント「Tools reference」（code.claude.com/docs/en/tools-reference.md）
- Claude Platform ドキュメント「Tool search tool」（platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool）
| 挙動 | 公式ドキュメントページ | 代わりの手がかり |
|---|---|---|
① クエリ形式3種（select: 等） |
記述なし | GitHub Issue #31002（v2.1.31 で追加との独自調査・公式未文書化と報告者が明言）、Anthropic製MCP instructions に実例 |
| ② No matching deferred tools found | 記述なし | API仕様書の「該当なしは空の結果を返す（エラーではない）」という近縁記述のみ |
| ③ 切断時の no longer available 化 | 記述なし | GitHub Issue #38043 にシステムメッセージ原文の引用。再接続後の復帰可否は報告が割れている |
| ④ 一括ロード推奨 | 直接的な記述なし | Anthropic製MCPサーバー（computer-use / claude-in-chrome）の instructions に明記。公式ページには「頻用ツールは非遅延に」の助言のみ |
念のため強調しておくと、これは「2026-07-09時点の調査で記述がなかった」という話だ。Claude Code のドキュメントは更新が速く、これらの挙動も将来文書化される可能性は十分ある。ただ少なくとも現時点では、公式ドキュメントを読んでも出てこない。実測ログと GitHub Issue、そして製品内に実在する instructions テキストが手がかりのすべてだった。
ツール定義の「常駐コスト」という見方
最後に、ToolSearch を少し引いた視点から見ておきたい。
ToolSearch が解決しているのは「常に読まれる情報を減らす」という問題だ。同じ問題は、実はツール定義以外の場所にもある。CLAUDE.md に書いた指示・ルールは、ツール定義と同じように毎セッション読み込まれ、コンテキストを消費し続ける。私は以前、自分の CLAUDE.md を実際に削ってみた記録を書いたが、あれは指示の常駐コストの話で、今回の ToolSearch はツール定義の常駐コストの話だ。「本当に必要になる瞬間まで読ませない」という同じ設計思想が、別のレイヤーに適用されている。
MCPサーバーを増やすかどうか迷ったとき、「ツールが増える」ことだけでなく「常駐する定義が増える」ことをコストとして意識する。deferred tools と ToolSearch は、そのコストを構造的に下げるための仕組みだと理解しておくと、接続設計の判断がしやすくなる。
まとめ——自分の環境で確かめる3ステップ
本記事の内容は、私の環境（2026年7月8日時点）での実測に基づいている。挙動③のように環境やバージョンで差が出る可能性のある話も含むので、ぜひ自分の環境で確かめてほしい。手順は簡単だ。
- deferred リストを覗く: MCPサーバーを接続した状態で、Claude に「ToolSearch でキーワード検索して、いま deferred リストにあるツールを見せて」と頼む
-
エラーの曖昧さを体感する:
/mcpでサーバーを無効化した状態でselect:ツール名の ToolSearch を試す。「No matching deferred tools found」が返り、ツールの不存在と区別がつかないことを確認する - 切断→再接続の挙動を観察する: ロード済みツールがあるセッションでサーバーを切断・再接続し、ツールが復帰するか観察する。ここは報告が割れている挙動なので、確かめる価値が最も高い
公式ドキュメントが追いつくまでの間、頼りになるのは自分の実測ログだ。そして実測した結果が本記事や GitHub Issue の報告と食い違ったら、それ自体がバージョン差異の貴重な観測記録になる。
MCP やツール連携を含めた Claude Code の基礎を体系的に押さえたい方には、入門書が出ている。仕組みの全体像を先に持っておくと、本記事のような個別挙動の位置づけが分かりやすくなる。
- Claude CodeによるAI駆動開発入門（平川 知秀 著）
- 実践Claude Code入門（西見 公宏・吉田 真吾・大嶋 勇樹 著）
ツール定義の常駐コストを ToolSearch が下げてくれると分かると、次の問いが出てくる——では指示・ルール・手順のほうは、どのレイヤーに渡せば一番効くのか。
ルールが守られないのも、サブエージェントが動かないのも、多くは「どこに渡すか」の設計の問題だ。CLAUDE.md・サブエージェント・スキル・Playbook・メモリ・設定/権限・MCP という7つのレイヤーのうち、その情報はどこに置くべきなのか。それを一章ずつ解剖したのが、Zenn Books の「コードを書けない私がClaude Codeに『仕組み』を渡すまで」（Vol.4）だ。本記事で扱った MCP とツールの層は、その7レイヤーの最深部にあたる。
コードを書けない私がClaude Codeに「仕組み」を渡すまで（序章無料）
この記事は はてなブログ からのクロスポストです。