Claude Code caps a Model Context Protocol tool's description at 4,096 characters when the tool loads upfront, and at 16,384 characters when it sits behind tool search instead. Setting alwaysLoad to true on a server cuts every one of its tool descriptions down to the smaller limit, without touching the description text itself.
Upfront and deferred are not just a speed setting
Claude Code defers MCP tool definitions by default instead of loading every connected server's full tool schema at the start of a session. Tool names and server instructions load first, and a tool's complete definition loads once the model searches for a capability it actually needs. Tool search keeps MCP context usage low by deferring tool definitions until Claude needs them, and only tool names and server instructions load at session start, so adding more MCP servers has minimal impact on the context window.
That deferral is also why the character limit changes between the two modes. A tool that loads upfront has to fit inside the same context budget as the rest of the conversation on every single turn, so Claude Code enforces a tighter ceiling on it.
The two limits, side by side
| Loading mode | Description character limit | How a tool ends up there |
|---|---|---|
| Loads upfront | 4,096 | alwaysLoad set to true on the tool or the server, or tool search turned off |
| Loads through tool search (deferred) | 16,384 | Default behavior, with alwaysLoad left out and tool search on |
| auto or auto:N threshold | 4,096 while usage stays under the percentage, 16,384 once tool search turns on | ENABLE_TOOL_SEARCH set to auto or auto:N |
Claude Code cuts a tool description or server instructions that run past whichever limit applies, and the model sees only the text before the cut. There is no error and no warning line in the terminal, just a shorter description than the one the server actually sent.
Here is the actual gap between the two limits, checked locally instead of eyeballed:
$ python3 -c "
upfront = 4096
deferred = 16384
print(f'upfront limit: {upfront} chars')
print(f'tool search limit: {deferred} chars')
print(f'difference: {deferred - upfront} chars')
print(f'ratio: {deferred/upfront:.1f}x')
"
upfront limit: 4096 chars
tool search limit: 16384 chars
difference: 12288 chars
ratio: 4.0x
A tool description written with the 16,384 character budget in mind, enough room for several worked examples and edge cases, loses three out of every four characters the moment its server sets alwaysLoad to true. Whatever text came first in the description survives the cut, so examples placed near the end of a long description are usually what disappears.
Per-tool opt-in, and the override that beats it
A server author can mark a single tool to always load upfront by setting anthropic/alwaysLoad inside that tool's _meta object:
{
"name": "search_tickets",
"description": "Searches the ticket tracker by keyword",
"_meta": {
"anthropic/alwaysLoad": true
}
}
The person who configures the server can override that per-tool choice for the whole server. Setting alwaysLoad to true at the server level forces every one of its tools upfront regardless of what each tool's own _meta asked for:
{
"mcpServers": {
"core-tools": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"alwaysLoad": true
}
}
}
Setting alwaysLoad to false at the server level does the opposite. It keeps every tool deferred, including the ones a server author marked to load upfront with their own _meta setting. Only when the server's configuration leaves alwaysLoad out do those per-tool marks take effect.
The auto threshold most setups never touch
Tool search also runs in a threshold mode. Setting ENABLE_TOOL_SEARCH to auto keeps tools that would otherwise be deferred loading upfront as long as their combined definitions stay under 10 percent of the context window. Once that total reaches 10 percent, tool search turns on for those tools. auto:N runs the same check against a custom percentage instead of the fixed 10:
# Use a custom 5% threshold
ENABLE_TOOL_SEARCH=auto:5 claude
# Disable tool search entirely
ENABLE_TOOL_SEARCH=false claude
A session with a couple of small MCP servers can sit under that threshold and keep every tool upfront at the 4,096 character limit without anyone setting alwaysLoad anywhere. Connect another server with a long tool list, cross 10 percent, and the same session switches those tools to deferred loading and the 16,384 character limit, with no configuration change on your side.
Turning tool search off entirely
Tool search can also be turned off at the permission layer instead of the environment variable:
{
"permissions": {
"deny": ["ToolSearch"]
}
}
Denying the ToolSearch tool has the same practical result as setting ENABLE_TOOL_SEARCH=false: MCP tools load upfront instead of being deferred, and each keeps the 4,096 character ceiling that applies to an upfront-loaded description.
What to check before writing a long tool description
Check the active .mcp.json entry for the server before assuming a tool gets the full 16,384 character budget, since alwaysLoad can be set there by someone else on the team and silently pin every tool to the smaller limit.
Keep a tool's description inside 4,096 characters when it genuinely needs to stay visible on every turn, instead of writing for the deferred limit and hoping the tool never gets pinned upfront later.
Raising CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH to 8192 moves both numbers to the same place at once. The upfront limit goes up to 8,192 characters and the deferred limit comes down to 8,192 characters, closing the four times gap between the two modes entirely.
Top comments (0)