🦀

Claude Code の ENABLE_TOOL_SEARCH=1 の挙動を理解する 2026/01

に公開
2026/01/26

【2026-01-26 追記】Claude Code ver.2.1.7 で、MCP Search が環境変数なしで有効になっています。挙動に関しては、この記事と変わったいないのです。

この記事はリバースエンジニアリングによる推測も含みます。この変更が現時点で表に出ておらず、取り下げられる可能性もあります。

Claude Code を含め、多くのコーディングエージェントでは、ファイル操作や外部との通信を行う際に MCP(Model Context Protocol) を用います。この MCP は、AI Agent とサードパーティーのサービスを繋ぐ仕組みと理解されている方が多いように思います。しかし、これは半分間違いで AI Agent が利用する API 呼び出しを定義する広義的な標準フォーマットであり、その適用範囲は内部的に定義された Tool 等も含まれます。

https://modelcontextprotocol.io/docs/getting-started/intro

Claude Code の Tool が MCP 定義されていることは Claude Code を Server として起動することで確認できます。以下のコマンドを実行することで、Claude Code は MCP Server として起動します。

him0 ~ ❯ claude mcp serve

MCP のフォーマットに従っているので Claude Code の Tool を Codex から呼び出すなんてことも、できるっちゃできというのが、MCP の面白いところですね。

MCP をコマンドライン上で実行できる MCPorter を使って対象の MCP Server の情報を Dump すると Server 自体の Description や Tool の引数、Description が確認できます。

him0 ~ ❯ npx mcporter list --stdio "claude mcp serve"
claude-mcp

  /**
   * Launch a new agent to handle complex, multi-step tasks autonomously.
   * The Task tool launches specialized agents (subprocesses) that autonomously handle complex tasks.
   * Each agent type has specific capabilities and tools available to it.
   * Available agent types and the tools they have access to:
   * When using the Task tool, you must specify a subagent_type parameter to select which agent type to
   * use.
...

こちらも読んでみると面白いので、ぜひ見てみてください。

本題 ENABLE_TOOL_SEARCH=1

MCP は MCP Server 自体の Description や Tool の Description は提供側が定義します。AI Agent 側は、それらを読んで利用を判断するので、ここで情報が足りなかったり、間違っていたりすると AI Agent は Tool の呼び出しに失敗したり、誤った呼び出しを行い期待した成果が得られない状態になってしまいます。

Claude Code の組み込みの Tool のように、AI Agent と Tool 定義を行う提供元が同じの場合、呼び出しの挙動に対応して、Description を AI Agent の System Prompt を更新することができますが、サードパーティーの MCP は、どんな AI Agent から呼び出されるか分からないので自ずと、丁寧な説明が必要になり、コンテキストウィンドウを圧迫するという問題が発生します。

この課題に対して、Anthropic は MCP の定義を LLM のコンテキストウィンドウにいきなり突っ込むのではなく、Tool Search Tool という、Tool 自体を Search する Tool を一段挟んで、段階的に Tool を有効化することで、コンテキストウィンドウの圧迫を回避しつつ、Tool の呼び出しを行える仕組みを提案、提供しています。

https://www.anthropic.com/engineering/advanced-tool-use

現在は、Claude API でこの仕組みが利用できますが、Claude Code に関しても、実験的な実装が入っており ENABLE_TOOL_SEARCH=1 を有効にすることで、この挙動を確認することができます。

今回は mcp__claude-in-chrome__tabs_context_mcp の呼び出しを例に挙動を見てみたいと思います。

ENABLE_TOOL_SEARCH 未設定のとき

chrome に関する指示を行うと mcp__claude-in-chrome__tabs_context_mcp の呼び出しが直接行われます。

ENABLE_TOOL_SEARCH 未設定

コンテキストを確認するとコンテキストウィンドウに claude in chrome の tool が含まれていることが確認できます。

コンテキストの状況

ENABLE_TOOL_SEARCH 有効のとき

ENABLE_TOOL_SEARCH=1 を設定すると、MCPSearch という Tool が呼び出され、そのあとで、mcp__claude-in-chrome__tabs_context_mcp が呼び出されます。

ENABLE_TOOL_SEARCH 設定済み

コンテキストを確認すると、今回呼び出した mcp__claude-in-chrome__tabs_context_mcp は loaded となり、token 数が表示されています。

一方で他の claude in chrome の tool は、token 数の表示がなくなり、コンテキストウィンドウに含まれない状態になっていることが確認できます。

コンテキストの状況

defer_loading の有効化

振る舞いから Tool Search Tool を Claude Code でも利用できる様にしているのであろうという予想のもと、どの様に通信されているかを Dump して挙動を確認します。
https://www.anthropic.com/engineering/advanced-tool-use

対象の環境変数を有効にしたことで見られる変化として、やはり defer_loading が、MCP tools に付加される挙動が確認できました。このフラグを付加することで、Tool 定義がいきなりコンテキストウィンドウに投入されない様になります。

{
  "name": "mcp__claude-in-chrome__tabs_context_mcp",
  "description": "Get ...",
  "input_schema": {
    "type": "object",
    "properties": {
      "createIfEmpty": {
        "type": "boolean",
        "description": "Creates a new MCP tab group if none exists, creates a new Window with a new tab group containing an empty tab (which can be used for this conversation). If a MCP tab group already exists, this parameter has no effect."
      }
    },
    "required": []
  },
  "defer_loading": true
},

Tool Search という名称上、気になったのが、どの Tool まで、defer_loading に突っ込まれるのか言うところだったので確認してみたところ、Claude Code の組み込みのツールに関しては、defer_loading は付加されず、これまで通りコンテキストウィンドウに最初から投入される挙動になることも確認できました。このあたりはよく使うし、コンテキストのチューニングがしやすいから、遅延ロードは不要と言う判断をしたこと、また、defer_loading を使う際はその様に判断すべきということが学べます。

{
  "name": "Skill",
  "description": "Execute ...",
  "input_schema": {
    "type": "object",
    "properties": {
      "skill": {
        "type": "string",
        "description": "The skill name. E.g., \"commit\", \"review-pr\", or \"pdf\""
      },
      "args": {
        "type": "string",
        "description": "Optional arguments for the skill"
      }
    },
    "required": [
      "skill"
    ],
    "additionalProperties": false,
    "$schema": "http://json-schema.org/draft-07/schema#"
  }
},

MCPSearch の Tool Description を探る

MCPSearch Tool の Description も確認してみます。

MCPSearch は、Select:xxx 形式の MCP の有効化と、Keyword による有効化に対応しており、Keyword のときは、マッチするであろう 5つの MCP が順位付けられて返却される仕組みになっていることが分かります。

また MCPSearch の Description は、defer_loading が有効となった Tool の一覧が渡る挙動が確認できました。Select:xxx 形式は、この一覧があるので、実現できるということです。

"name": "MCPSearch"
"Desciprion": Search for or select MCP tools to make them available for use.

**MANDATORY PREREQUISITE - THIS IS A HARD REQUIREMENT**

You MUST use this tool to load MCP tools BEFORE calling them directly.

This is a BLOCKING REQUIREMENT - MCP tools listed below are NOT available until you load them using this tool.

**Why this is non-negotiable:**
- MCP tools are deferred and not loaded until discovered via this tool
- Calling an MCP tool without first loading it will fail

**Query modes:**

1. **Direct selection** - Use `select:<tool_name>` when you know exactly which tool you need:
   - \"select:mcp__slack__read_channel\"
   - \"select:mcp__filesystem__list_directory\"
   - Returns just that tool if it exists

2. **Keyword search** - Use keywords when you're unsure which tool to use:
   - \"list directory\" - find tools for listing directories
   - \"read file\" - find tools for reading files
   - \"slack message\" - find slack messaging tools
   - Returns up to 5 matching tools ranked by relevance

**CORRECT Usage Patterns:**

<example>
User: List files in the src directory
Assistant: I can see mcp__filesystem__list_directory in the available tools. Let me select it.
[Calls MCPSearch with query: \"select:mcp__filesystem__list_directory\"]
[Calls the MCP tool]
</example>

<example>
User: I need to work with slack somehow
Assistant: Let me search for slack tools.
[Calls MCPSearch with query: \"slack\"]
Assistant: Found several options including mcp__slack__read_channel.
[Calls the MCP tool]
</example>

**INCORRECT Usage Pattern - NEVER DO THIS:**

<bad-example>
User: Read my slack messages
Assistant: [Directly calls mcp__slack__read_channel without loading it first]
WRONG - You must load the tool FIRST using this tool
</bad-example>

Available MCP tools (must be loaded before use):
mcp__claude-in-chrome__javascript_tool
mcp__claude-in-chrome__read_page
mcp__claude-in-chrome__find
mcp__claude-in-chrome__form_input
mcp__claude-in-chrome__computer
mcp__claude-in-chrome__navigate
mcp__claude-in-chrome__resize_window
mcp__claude-in-chrome__gif_creator
mcp__claude-in-chrome__upload_image
mcp__claude-in-chrome__get_page_text
mcp__claude-in-chrome__tabs_context_mcp
mcp__claude-in-chrome__tabs_create_mcp
mcp__claude-in-chrome__update_plan
mcp__claude-in-chrome__read_console_messages
mcp__claude-in-chrome__read_network_requests
mcp__claude-in-chrome__shortcuts_list
mcp__claude-in-chrome__shortcuts_execute
mcp__ide__getDiagnostics
mcp__ide__executeCode

まとめ

ENABLE_TOOL_SEARCH に関しては、Claude API の拡張を利用する正当進化であり、コンテキストウィンドウの圧迫問題を仕組みで解決できる、かなり嬉しいアップデートになりそうということが確認できました。

defer_loading に関しては、どのくらい正確に動作するのかは未知数ですが、挙動のチューニングに関しては、 Tool Search Tool のドキュメントに従うと何か手がかりになる可能性が見えました。

Discussion