Disable Claude Code tool search? Try MCP alwaysLoad instead

Should you disable tool search in Claude Code to get it to use your MCP tools? I tested the alternative the docs offer, marking a single tool with _meta: {"anthropic/alwaysLoad": true}, against ENABLE_TOOL_SEARCH=false in 336 headless runs. Both got the tool called in 96 of 96 runs. The per-tool flag added 238 tokens to every request; tool search off added 12,016, because it also loads Claude Code’s own deferred tools. With the default deferred loading, a vaguely named tool was called in only 30 of 48 runs.

This is the fourth post on agent memory and MCP, after a recall test of an MCP memory server. In the 97-line server post I found that Claude Code’s tool search hides tool descriptions until Claude asks for a tool, so names decide whether a tool gets called. That post ended on a note I hadn’t tested: the docs describe a way to load just one tool upfront. This is that test.

What is MCP tool search in Claude Code?

Since tool search became the default, Claude Code doesn’t put MCP tool definitions in the prompt. Claude sees a list of tool names (and each server’s instructions), and calls a built-in ToolSearch tool to load a definition before using it. That keeps context small when you have many servers. The cost is that Claude has to decide to look, based on a name like mcp__notes__search_notes or mcp__s1__query.

The Claude Code MCP docs give three ways around it:

• Tool search off: ENABLE_TOOL_SEARCH=false loads every tool upfront, for every server.
• Per server: "alwaysLoad": true in a server’s entry in your MCP config loads all of that server’s tools.
• Per tool: a server author sets "anthropic/alwaysLoad": true in a tool’s _meta, and Claude Code loads that one tool upfront.

The per-tool flag is the only one the server author controls, so it is the one a server can ship with.

How I tested it

The server is the notes search from the earlier post: BM25 over seven Markdown posts from this blog, with two tools, search_notes and read_note. I added one environment switch that puts the flag on search_notes only. With the TypeScript SDK, registerTool passes _meta straight through to tools/list:

const alwaysLoad = env.ALWAYS_LOAD === "search" ? { _meta: { "anthropic/alwaysLoad": true } } : {};

server.registerTool("search_notes", {
  description: "Full-text search over ... Markdown notes and blog posts in a local folder. ...",
  inputSchema: { query: z.string(), limit: z.number().int().min(1).max(10).default(3) },
  ...alwaysLoad,
}, handler);

Seven conditions: clear names (notes / search_notes) under deferred, per-tool, per-server and tool search off, and vague names (s1 / query, described as “Runs a query.”) under deferred, per-tool and tool search off. Each got the same 12 questions about the posts, such as “How much RAM did the Hermes Agent gateway use while idle?”, twice: hinted (“Check my notes. …”) and bare. Two repetitions, 336 runs of claude -p with Claude Code 2.1.304 and Claude Sonnet 5.5.

One change from the earlier benchmarks: I blocked Claude Code’s file and shell tools (Bash, Read, Grep, Glob) and subagents. In my first attempt a vague-name run went looking for the answer with grep -r over the whole home folder, which could reach the corpus. With those blocked, the MCP server is the only way to the notes, and a run that doesn’t call it can only answer from memory or say it doesn’t know. CLAUDE.md files and auto-memory were off, as before.

Does alwaysLoad make Claude Code use the tool?

Yes, every time. Calls to the search tool, out of 48 runs per condition (24 hinted, 24 bare):

Loading	Clear names	Vague names	ToolSearch before the first call
Deferred (default)	44	30	every run that called it
Per-tool alwaysLoad (search tool only)	48	48	0
Per-server alwaysLoad	48	(not run)	0
Tool search off	48	48	0

The gap is all in bare questions. Deferred, the clear tool was called in 20 of 24 bare runs and the vague one in 7 of 24. Per-tool, both were 24 of 24.

When the deferred vague tool wasn’t called, Claude didn’t make things up. It said it couldn’t find the data (“I won’t guess at numbers”), except for two questions it could answer from memory (Ollama’s default context and Hermes Agent’s minimum context). That left 34 of 48 right answers deferred, against 48 of 48 with the tool loaded upfront. With clear names, every mode got 48 of 48: the four deferred runs that skipped the tool were those same two memory questions.

Loading upfront also saved a turn. Deferred runs took a median of 4 turns with clear names against 3 for the other modes, because Claude first calls ToolSearch. Mean wall time per run was 11.9 s deferred against 9.1 to 9.8 s for the three upfront modes.

How much context does alwaysLoad cost?

I measured the input tokens of a one-turn “Reply with the single word OK.” prompt, three launches per setup. The numbers were identical across launches:

Setup	Input tokens	Added by MCP and loading mode
No MCP server	9,704
This server, deferred	9,727	+23
Per-tool alwaysLoad on search_notes	9,942	+238
Per-server alwaysLoad (both tools)	10,055	+351
Tool search off	21,720	+12,016
No MCP server, tool search off	21,369	+11,665

So tool search off is not really a setting for your server. My two tools are 351 tokens of the 12,016; the other 11,665 are Claude Code’s own deferred tools, loaded with or without any MCP server. (The base is smaller than in the earlier post because blocked tools aren’t sent at all.)

Two more checks from the same runs. A server entry with "alwaysLoad": false overrode the tool’s own flag (back to +23), as the docs say. Both flags together cost the same as the per-server one.

Is there a catch with only one tool loaded?

One. read_note stayed deferred, and Claude often called it without loading it first. In 25 of the 48 clear-name per-tool runs, Claude called read_note before ToolSearch had returned its definition, 27 calls in all. 23 of them worked, because Claude guessed the argument from the search results, which list a path for each file. 4 failed: Claude sent {} or {"query": "select:mcp__notes__read_note"} (the ToolSearch input, sent to the wrong tool), and the SDK answered with an input validation error. Claude then loaded the tool and recovered, so no answer was lost. With vague names it happened in 5 runs, 8 calls, 3 of them errors. The tool results came from Claude Code’s session transcripts; bench/early_calls.py in the repo counts them.

The same failure was reported in a GitHub issue on Agenta: a deferred tool called before its schema loads and sent empty arguments. If your follow-up tools have required arguments, either mark them too or make sure the error names the missing argument. Here the SDK’s message (“expected string, received undefined at path”) was enough for Claude to recover.

Does a slow server lose its alwaysLoad tools?

The docs say a per-tool flag doesn’t make startup wait for your server, while the per-server flag does (up to 5 seconds). I expected a slow server to come up after the first request and miss out. So I made the server sleep 0, 10 or 25 seconds before connecting, in plain -p mode and in --input-format stream-json (the Agent SDK’s mode), two runs each.

It never happened. In all 24 per-tool and per-server runs Claude Code waited for the server and the first request already had the tool: 9,977 input tokens per-tool and 10,090 per-server, the same as with no delay. All 36 runs, deferred ones included, answered right. The CLI reference explains it: with --mcp-config and -p, Claude Code waits for pending servers up to MCP_TIMEOUT, 30 seconds by default. A 25 second server simply made each run 25 seconds longer. Interactive sessions connect in the background, so the startup difference may matter there; I didn’t test that.

Does alwaysLoad work with Claude Haiku?

The Agenta issue above saw Claude Haiku defer tools too, so I ran a smaller pass with Claude Haiku 5.5: deferred and per-tool, clear and vague names, one repetition, 96 runs (USD 0.23).

Haiku 5.5, 24 runs each	Called the tool	Right answer	Runs that tried a blocked file or shell tool
Clear names, deferred	22	23	8
Clear names, per-tool alwaysLoad	23	24	0
Vague names, deferred	19	22	22
Vague names, per-tool alwaysLoad	23	22	2

Haiku uses tool search the same way, and the flag worked the same way: the only per-tool runs that skipped the tool were the Ollama question, answered from memory. Haiku looked for the tool more often than Sonnet did when it was deferred (19 of 24 against Sonnet’s 30 of 48), but the last column shows how: with a deferred vague tool, it first tried Bash, Grep, Glob, Read, and even writing a probe file in 22 of 24 runs, all refused. With the tool loaded upfront it went straight to it. Three Haiku answers were wrong after calling the tool, because it answered from a search snippet instead of reading the note.

Should you mark your MCP tools alwaysLoad?

For the one or two tools that make your server worth installing, yes. Based on these runs:

1. Server authors: put _meta: {"anthropic/alwaysLoad": true} on the entry tool (the search, the lookup), and leave rarely used tools deferred. Here it cost 215 tokens for one tool, and it does not depend on the person installing the server.
2. Mark the follow-up tool too if its arguments are required, or write an error message that says how to call it. Calls to deferred tools before they load are not rare.
3. Don’t turn tool search off for one server. It got the same result for 50 times the context, and that context is paid on every request of every session.
4. Users who can’t change the server can set "alwaysLoad": true on that server’s entry. It loads all of its tools, which for a big server is the cost tool search was meant to save.

Clear names and server instructions still matter: they are what Claude sees for the tools you leave deferred. In the Skill vs MCP post, two sentences of server instructions took the MCP side from losing to a Skill to winning 45 runs to 0.

What broke and what I’d do differently

• My first run leaked into the home folder. With Bash allowed but not listed, a vague-name run grepped ~ for “gemma”. I stopped it after 10 runs, blocked Bash, then saw Claude switch to its Grep and Glob tools, and blocked those too after 16 more. Both partial runs were discarded. A benchmark of whether a model uses one tool needs every other route closed.
• I lost the tool results for the main runs. My parser kept tool calls but not their results, so the early-call errors came from Claude Code’s transcripts, matched to runs by order and prompt. The script checks that the tool-call sequence matches for every run (it did for all 336), and the parser now saves results.
• One model, one small server, one machine. The vague server had no instructions on purpose. A server with 40 tools, or a model other than Sonnet 5.5, may behave differently. The raw runs are in the repo if you want to compare.

The code, the questions and every run are in the project folder. The runs cost USD 8.98 at API prices for the 336 main runs (Claude Code reports it; I ran on a subscription).