你的工具描述如今是两份文档、两套预算,而只有短的那一份决定这个工具会不会被找到。
写一份又长又细致的描述,其中大部分永远不会被那个真正要紧的步骤读到:截至 2026 年 11 月,Claude Code 默认把 MCP 工具定义延后加载,而那个必须匹配到你工具的检索只会读前 4,096 个字符——尽管一个被延后的描述最长可以写到 16,384 个字符。可发现性不再是写作问题,而是预算问题——头上那几百个词是一个检索界面,其余部分是写给「已经进门的读者」的文档,而最有杠杆的那个决定压根不是措辞,是这个工具要不要进「总是加载」的那一组。
步骤 1选择一直都是检索。现在它是针对一个你管不着的索引做检索。
面对一个任务和一串工具,模型没有遥测、没有使用统计,也没有便宜的「先试一个看看」。它是从文字里挑的,这正是名称和描述并非元数据、而是索引本身的原因。变了的地方在于:这个索引如今是字面意义上的索引。在工具检索开启时——这是 Claude Code 的默认值,也是 Anthropic API 上 Opus 4.5、Sonnet 4.5 与 Haiku 4.5 的同一默认值——会话开始时只加载工具名称与服务器说明。完整定义要等某个检索步骤去找它时才抵达。
这把失效模式挪了位。此前一个描述糟糕的工具是「在场但容易混」;现在一个描述糟糕的工具可以在整场会话里都不在模型的工作集里,而对话记录里没有任何一句话说明这件事。症状是一个自信地绕远路把任务做完的智能体——它去写一条 shell 管道,而不是调用你的查询工具——因为从它的位置上看,那个工具压根不存在。处理「模型无视我的工具」这类反馈时,先问那份定义究竟有没有被加载过,而不是先问描述是否清楚。
这与 MCP 上下文过载 从运维侧描述的是同一次转变。落到作者侧,结论更窄也更锋利:你不再是为模型写字,你是在为一个挡在你和模型之间的检索步骤写字。
步骤 2名称就是索引条目,所以它是唯一保证会被读到的文字。
不论是否延后加载,名称都会在开头加载,这让它成为你整个界面上唯一有保证读者的那一块。一个好名字说清动作和对象,并且跟邻居区分得开:refund_order 胜过 process;search_customers 胜过 lookup。工具一多,按服务与资源做命名空间仍然是最有效的消歧手段——asana_projects_search 对 asana_users_search 对 jira_issues_search——因为共享前缀在任何描述被取回之前,就把这个工具放进了一个家族里。
# Unnamespaced: four names, no family, nothing to retrieve on search(q) lookup(q) find(q) query(q) # Namespaced by service + resource: the name alone narrows the search asana_projects_search(q) asana_users_search(q) jira_issues_search(q)
在延后加载之下还要补一条:名称里该带上用户会用来描述这个任务的词,而不只是你的 API 用来称呼这个资源的词。一个叫 crm_opportunity_stage_set 的工具很精确,但在检索「把这单标成已成交」时,会输给任何名字更贴近那句话的东西。名称如今既在做消歧的活,也在做关键词的活。
步骤 3两套预算、一个字段:4,096 个字符让你被找到,16,384 个字符让你被正确调用。
Claude Code 里的默认上限是 4,096 和 16,384 个字符,而这个划分与其说是尺寸限制,不如说是两类读者之间的划分。服务器说明,以及任何开头就加载的描述,保持 4,096 字符的上限。一个被延后的描述最长可以到 16,384。但那个匹配步骤本身——决定你的工具究竟会不会被取回的那一步——只会读短上限之内的那部分。如果运维方设了 CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH,这两个数会一起动:抬高开头加载的上限、同时压低延后加载的上限,所以你连这个比例都不能指望。
实际后果是一份分成两半、两半工作不同、而次序被锁死的文档:
- 先,在 4,096 字符之内:检索会用到的那些词。这个工具做什么、这个领域的名词、用户对这个任务的说法,以及与最近邻工具的边界——「用它来为一笔已完成的订单退款;要取消一笔未发货的订单,请用
cancel_order」。这一半是检索界面。在这里解释你的内部实现,是花掉的预算。 - 之后,直到 16,384:只有命中之后才会被读到的材料。可照抄的调用、ID 格式、单位、那个最常见的参数组合、错误语义。细节属于这里,而且它在某种意义上是免费的——没有被取回的工具不会为它付钱。
下面是这个划分的一个范例,这个工具的邻居是另外三个检索类工具:
# FIRST 4,096 CHARS — searchable. Keywords, scope, boundary. Search closed-won and closed-lost deals by customer, amount, owner or close date. Use for questions about revenue already booked, deal history, win rates, and "what did we sell to X". Returns deal records, not line items. Do NOT use for open pipeline or forecasts — that is crm_pipeline_search. Do NOT use for invoices — that is billing_search. # REMAINDER — only read after a search hit. Detail, not keywords. Example: deals closed by one owner last quarter -> crm_deals_search(owner_email="a@co.com", closed_after="2026-07-01", stage="closed_won", limit=50) amount is minor units (cents). close_date is ISO-8601 date, no time. limit defaults to 20, max 200; page with the opaque `cursor` returned. A customer with no deals returns [] and is not an error.
把这一切写成一段不加区分的长文字,团队通常会同时拿到两头最差的结果:关键词落在了末尾、匹配永远看不到,而调用范例坐在最前面、烧掉了检索预算。请把「会被检索的词」放在靠前的位置,把 契约细节 放在后面。
步骤 4这个工具究竟会不会被延后,如今是最大的那个决定,而你只拥有它的一半。
服务器作者可以在某个工具的 _meta 里设 "anthropic/alwaysLoad",把它排除在延后之外;而安装这个服务器的运维方可以对整个服务器设 alwaysLoad——在任一方向上覆盖作者的逐工具选择。于是「总是加载」这一组是由两方协商出来的,而双方的激励并不一致:每个作者都相信自家工具每一轮都用得上,而付账的是运维方,用的是他们的对话从此不再拥有的上下文。
把它花在那少数几个真的服务于每一轮的工具上,其余的接受延后。有用的判据不是「重要不重要」,而是模型会不会知道该去找它。一个任务一出现模型就会去检索的工具——退款、迁移、部署——被延后并不损失什么。真正该进「总是加载」的,是那种必须被提醒它存在才会被正确使用的工具:它该在动手前跑的那道策略检查、它想不到自己需要的那次上下文查询。正是这些工具一旦不在工作集里,行为会悄悄变化,而不只是多出一个检索步骤。
不要把「延后可用」当成设计前提。在使用 HIPAA 配置的会话里,工具检索是关闭的、而且无法重新开启;Azure 上托管的 Microsoft Foundry 部署会在服务端拒绝它、并退回到全部开头加载;早于 Opus 4 与 Sonnet 4 的模型全部开头加载;而 ENABLE_TOOL_SEARCH=auto 会在工具定义总量低于上下文窗口的 10% 时把它们开头加载。上面每一种情形里,你那 16,384 个字符的描述都会突然变成一笔开头就付的成本、被压到 4,096 的上限、再乘上你的工具数量。一个带 60 个啰嗦工具的服务器,在延后加载之下表现良好,没有延后则根本不可用。
步骤 5协议给你的是缓存与次序,不是发现。
很容易把延后加载读成一项协议特性。它不是:2026-07-28 那版 MCP 修订加入了 server/discover——一个让客户端预先了解服务器能力的可选 RPC——而规范明确写着它不是必需的。延后加载活在宿主与客户端这一层,这正是为什么它的行为写在某一家厂商的文档里、用那家厂商的环境变量配置,而不是在链路上协商出来的。
同一版修订真正给作者的东西值得用起来。tools/list 的响应现在带上了 ttlMs 与 cacheScope,客户端因此可以缓存你的列表而不必反复取;并且列表响应有确定的次序,这让上游的提示缓存在多次调用之间保持稳定。这两件事合起来意味着:一个以稳定次序返回工具、并给出诚实 TTL 的服务器,对调用方的成本实质性地低于一个会把列表洗牌的服务器——而一个频繁搅动自己列表的服务器,正在失效它看不见的那些提示缓存。变更通知则搬到了单一的 subscriptions/listen 流上、由客户端按通知类型逐项订阅,所以一份会在会话中途变化的工具列表,如今是你去宣告的东西,而不是客户端靠轮询发现的东西。完整清单见 2026-07-28 修订;次序稳定性为什么真的值钱,见 提示缓存。
步骤 6什么时候打磨描述已经不是瓶颈。
描述质量有天花板,而在延后加载之下这个天花板来得更早。再怎么措辞也救不了一个形状错了的工具(K1–K3)、一个边界划错了位置的工具(K2),或者一个压根不该在这张清单上的工具。有三种签名告诉你该停止改文案了:
- 模型找到了这个工具,但调用错了。检索界面起作用了,问题在契约。把修复挪进 schema 和范例里。
- 模型从来找不到它,而一个描述几乎相同的同级工具被调用了。两个工具在抢同一个位置——这是粒度决定,不是措辞决定。合并它们,或者让边界变成结构性的。
- 随着你加入不相关的工具,选择准确率下降。这是库存问题、不是文案问题。精简「总是加载」那一组、其余延后,然后重新测量。
更深一层的意思是:「文档写得更好」和「工具更少」不再是同一个问题的两种替代解法。延后加载把它们解耦了——库存规模如今主要是检索质量与名称质量的问题,而它过去带来的那笔上下文成本,只由你选择留在「总是加载」里的那些工具支付。这让「总是加载」清单成为该按期审计的那样东西,而描述成为该写一次、分成两半、按正确次序写好的那样东西。
今天就做:列出你服务器的工具,标出那些必须每一轮都在上下文里的,并检查这一组是否小到每个都能活在 4,096 个字符之内。其余的,把领域名词和与邻居的边界挪到描述的前半部分、把范例推到后面。然后在加入第 61 个工具之前,先读 MCP 工具设计 与 Skills、子智能体、MCP 与 Hooks 之辨。