MCP 预加载配置会压缩工具描述额度
素材指出,Claude Code 中预加载工具的描述上限为 4096 字符,经工具搜索延迟加载时则为 16384 字符。为服务器启用 alwaysLoad 会让其所有工具适用较小额度,配置变化本身无需修改描述。
AI 深度解读
同一份 MCP 工具描述,在 Claude Code 里可能只剩前 4,096 个字符,也可能保留到 16,384 个字符。按作者的说法,决定上限的是工具实际如何加载,服务端文本可以完全没变。
这篇文章提醒的是一个容易漏查的配置问题:开启 alwaysLoad 不只影响工具何时可见,还可能让描述尾部的示例、边界条件被静默截掉。不过,作者展示的本地计算只能证明两档预算相差四倍,不能单独证明 Claude Code 的实际截断行为。
工具提前加载,为什么描述反而更短
Claude Code 默认会延迟加载 MCP 工具定义。会话开始时先放入工具名称和服务器指令,等模型通过工具搜索找到需要的能力,再加载完整定义。模型先知道有哪些工具,需要使用时才看详细说明。
作者给出的两档限制是:
- 提前加载的工具,描述上限为 4,096 个字符。
- 通过工具搜索延迟加载的工具,描述上限为 16,384 个字符。
两者相差 12,288 个字符,比例是 4.0x。原文用 python3 -c 做了这组算术核对,但没有展示从 Claude Code 实际读取描述、检查截断位置的实验。
作者的解释是,提前加载的定义会持续占用对话上下文,因此预算更紧。这里计量的是字符,不是 token,不能直接拿这两个数推算模型上下文占比。
按原文描述,超过适用上限的工具描述或服务器指令会被截断,终端既不报错,也不显示警告。对于按 16,384 字符写满的描述,一旦切到提前加载,后四分之三就可能消失。
工具能被调用,不代表模型看到了完整的使用说明。
如果关键限制写在末尾,调用表现变差时,很容易把配置问题误判成模型理解能力不足。
谁能决定工具提前加载
工具作者可以在单个工具的 _meta 中设置 anthropic/alwaysLoad,让它提前加载。下面这段配置解决的是单个工具的加载选择:
{
"name": "search_tickets",
"description": "Searches the ticket tracker by keyword",
"_meta": {
"anthropic/alwaysLoad": true
}
}
要看的是 anthropic/alwaysLoad 这一行,它位于工具定义内部。
但使用方还可以在服务器配置里覆盖这个选择。下面这段配置会强制整个服务器的工具提前加载:
{
"mcpServers": {
"core-tools": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"alwaysLoad": true
}
}
}
要看的是服务器级的 alwaysLoad。按作者给出的优先级,它设为 true 时,所有工具都提前加载;设为 false 时,所有工具都延迟加载,包括工具作者明确标记为提前加载的那些。只有省略服务器级字段,单个工具的标记才生效。
所以,排查时不能只读 MCP 服务端源码。实际生效的 .mcp.json 同样重要,团队里的其他人可能已经在那里改过加载策略。
没写 alwaysLoad,也可能触发较小上限
另一个变量是 ENABLE_TOOL_SEARCH。
原文称,设为 auto 后,原本可延迟加载的工具,如果完整定义合计低于上下文窗口的 10%,仍会提前加载;达到 10% 后才启用工具搜索。也就是说,未设置 alwaysLoad,不等于工具一定延迟加载。
自定义阈值可以用 ENABLE_TOOL_SEARCH=auto:5 claude,把触发比例改为 5%。而 ENABLE_TOOL_SEARCH=false claude 会完全关闭工具搜索。
权限配置也有另一条入口:在 permissions 的 deny 中加入 ["ToolSearch"]。按原文说法,这与关闭工具搜索有相同的实际结果:MCP 工具提前加载,描述适用 4,096 字符上限。
因此,新增一个工具很多的服务器,可能让总定义量跨过阈值,进而改变其他工具的加载方式和描述预算。
原文最后还给出一个容易误解的参数:把 CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH 设为 8192,会让两档上限都变成 8,192。提前加载的上限提高,延迟加载的上限反而降低,它不是只把较小预算往上调。
我的判断
我认可作者提出的排查顺序:先确认加载方式,再讨论描述写得是否充分。对于依赖自然语言说明来选择参数、处理边界的工具,静默截断确实值得纳入故障排查。
但这篇文章的证据还不够完整。原文没有给出 Claude Code 版本、实现出处,也没有展示截断前后的模型可见内容。那段本地脚本只是计算 16384 - 4096 和两者比例,不能当作产品行为的验证。具体上限与覆盖关系,应先视为作者报告的行为。
长描述也未必更有效。原文没有比较长短描述的调用成功率,没有给出不同加载策略的延迟数据。多放几个示例可能有帮助,也可能让关键规则更难找到,不能仅凭字符预算下结论。
相较于单纯调大上限,我更倾向于先压缩重复说明,把用途、必要约束和关键示例前置。这样即使配置改变,描述最前面的内容仍然有用。
能拿来做什么
- 给日常 AI 编程使用的 MCP 工具排查异常时,先检查
.mcp.json、ENABLE_TOOL_SEARCH和ToolSearch权限,再判断是否需要改提示词。 - 如果前端或 Node 项目中的某个工具必须提前加载,可以先按 4,096 字符预算整理描述,把决定能否正确调用的约束放在前面。
- 团队新增 MCP 服务器后,可以选几个常用工具核对加载方式和说明是否完整,避免自动阈值变化后仍沿用旧判断。
- 如果准备使用
CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH=8192,应同时检查原有长描述;按原文说法,超过 8,192 字符的延迟加载描述也会受影响。