Claude Code v2.1.296, released by Anthropic on 9 October 2026, raises the default limit on MCP tool descriptions and server instructions from 2,048 to 4,096 characters. For teams that build MCP servers, text that used to be cut off now reaches Claude, but longer descriptions also cost context when tools load up front.
What was released
The change was announced by Anthropic on 9 October 2026 in the Claude Code v2.1.296 release notes, which change "the default limit on MCP tool descriptions sent up front and on MCP server instructions from 2,048 to 4,096 characters". Nothing needs to be switched on: anyone who updates Claude Code to v2.1.296 or later gets the new default, and servers do not need to change for it to apply.
What actually changed
The Claude Code MCP documentation explains what the limit does. Claude Code truncates each tool description and each server's instructions at the limit, so anything past it never reaches the model. The same page advises keeping both concise and putting critical details near the start. At the time of writing, that page still states the older 2,048-character default, so the release notes are the source for the new figure.
Two related controls are unchanged:
- The override still exists.
CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTHsets the limit for every MCP server in a session, in characters. It needs Claude Code v2.1.280 or later. Anyone who set it before keeps their own value, so the new default only applies where it is not set. - Tool search decides what loads up front. With tool search, which is on by default, only tool names and server instructions load at session start, and full tool definitions arrive when Claude searches for them. Server authors can mark a tool to load up front with
_meta["anthropic/alwaysLoad"], and users can setalwaysLoadfor a whole server.
The same release also adds autoCompactWindow for subagent definitions, so a subagent can compact earlier than the main conversation, a CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL variable to run every workflow agent on one model, and CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS to lengthen the backoff on overloaded (529) requests. It fixes Bash permission checks that auto-approved some commands assigning and then using the BASH_ARGV0 shell variable; these now ask for approval.
What it means for teams building MCP servers
If your team ships an MCP server that people use from Claude Code, the description is how Claude decides whether and how to call a tool. In CodeDTX's view, these are the practical steps:
- Find what was being cut off. Check which tool descriptions and server instructions run past 2,048 characters. Those are the ones whose closing text, often the constraints and examples, Claude has not been seeing on older versions. Read them again as Claude will now see them in full.
- Spend the room on rules, not marketing. Use the extra space for what prevents wrong calls: required argument combinations, units and formats, what the tool must not be used for, and what an error means. A longer sales-style summary adds context cost and no accuracy. Our guide to designing tools an AI agent can use covers what belongs in a description.
- Write server instructions for tool search. With tool search on, server instructions are what Claude reads to decide when to look for your tools. The docs suggest stating the kind of tasks your tools handle, when to search for them, and the key capabilities. That now has twice the room.
- Keep the important part first. Users on older versions, or with
CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTHset lower, still truncate at their limit. Put the constraint that prevents harm in the opening lines so it survives any cut-off. - Test against the version range you support. Run the same tasks on an older Claude Code and on v2.1.296 or later, and compare which tools Claude picks and how it fills arguments. A description that only works when read in full needs restructuring.
When to keep descriptions short
Longer descriptions are not free. Where tools load up front, every character sits in the context of every session. The MCP docs note that Claude Code turns tool search off when ANTHROPIC_BASE_URL points to a host that is not first-party, which is common behind a gateway, so all tools load up front there. Tools marked alwaysLoad behave the same way. On those set-ups, doubling description length across a large server is a direct context and cost increase, the trade-off covered in controlling AI agent running costs. If one tool needs pages of guidance, a separate documentation tool or resource is often a better home than its description. And if your agents talk to other agents rather than tools, MCP may not be the right protocol at all.
Frequently asked questions
What is the new MCP tool description limit in Claude Code?
From Claude Code v2.1.296, released by Anthropic on 9 October 2026, the default limit for MCP tool descriptions sent up front and for MCP server instructions is 4,096 characters, up from 2,048. Claude Code truncates text past the limit, so it never reaches the model. The CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH environment variable still overrides the default for every server in a session.
Do MCP server authors need to change anything for the new limit?
Nothing breaks, and the new default applies as soon as users update Claude Code. It is still worth reviewing any description or server instructions longer than 2,048 characters, because their closing text, often constraints and examples, was hidden on older versions. Keep the most important rules in the opening lines, since users on older versions or with a lower override still truncate there.
Do longer MCP tool descriptions use more context?
They can. With tool search on, which is the default, only tool names and server instructions load at session start, so longer tool descriptions cost context only when Claude loads those tools. Where tools load up front, such as behind a gateway that is not first-party or with alwaysLoad set, every description sits in every session, so longer text means more tokens on each request.
Should every MCP tool description use the full 4,096 characters?
No. Use the room only where it prevents wrong calls: argument rules, formats, limits on use and the meaning of errors. Simple tools with obvious inputs are better with short descriptions, which keep context use down where tools load up front. If a tool needs extended guidance, consider a separate documentation tool or resource that Claude reads only when it needs the detail.
