工具注解是提示,不是闸门

9 分钟读完

K15
深入解析 · 工具与能力设计

悲观默认值惩罚了那个老实闭嘴的服务端、奖励了那个张口就断言的服务端,所以注解永远当不了闸门。

如果你的审批弹窗会在工具声明 readOnlyHint: true 时跳过确认,那你就把「什么需要人来复核」这个决定,交给了那个正被复核的工具的作者。MCP 的四个注解是一套值得拥有的风险词汇,而规范也明说了它们是不可信输入——这意味着真正该造的东西,是一份服务端写不进去的、客户端侧的分类,并把注解降级为一个默认值和一个漂移告警。

步骤 1四个提示,而默认值才是从来没人读的那部分。

MCP 服务端里的一个工具可以带四个布尔注解。readOnlyHint 说这个工具不修改它的环境。destructiveHint 说如果它确实修改了什么,那改动可能是破坏性的、而不只是追加性的。idempotentHint 说用同样的参数重复调用不会产生额外效果。openWorldHint 说这个工具会碰到某个封闭本地域之外的东西——开放互联网、第三方 API。

关于这一组,有两个结构性事实比各自的含义更要紧。第一,destructiveHint 与 idempotentHint 只有在 readOnlyHint 为假时才有意义;在一个只读工具上,它们什么也没描述。第二——而这一条才是在真实环境里改变行为的那个——注解缺失时的默认值是刻意悲观的:

  • readOnlyHint 默认为 false——假定它会写。
  • destructiveHint 默认为 true——假定那次写有破坏性。
  • idempotentHint 默认为 false——假定重复一次会造成损害。
  • openWorldHint 默认为 true——假定它会出网。

作为安全默认值,这个方向显然是对的:一个没加注解的工具,被当成它可能是的那个最危险的东西。MCP 官方博客在 2026 年 3 月的一篇文章里把这组东西称为一套风险词汇,而作为词汇它配得上这个位置——在它存在之前,客户端根本没有一种标准方式去说「这个会删东西」。所有难办的事,都源自这套词汇自身答不了的一个问题:谁有资格说它。

步骤 2规范早已说明这些提示不可信,而那一句就是全部的设计约束。

协议没把这件事留给人去揣摩。它告诉客户端:除非注解来自一个客户端信任的服务端,否则就按不可信对待,并且不要让来自不可信服务端的提示去驱动工具使用决定。MCP 博客自己给的例子,就是一个自称只读、却在删文件的服务端。

请注意这一句排除掉了什么,因为它排除的比乍看上去要多。它排除了闸门。如果一个提示不能决定工具使用决定,那么「当 readOnlyHint 为真时跳过确认」就不是一项被许可的优化——它恰恰就是那句话所禁止的事,只不过被实现成了一种便利。更安静的那些变体也一样:把只读工具排除在审计日志之外、把它们从速率预算里省掉、让它们跑在一个自动批准的批次里而写操作被扣下复核。

而「除非服务端可信」这个口子,起的作用比它看起来小得多。对一个 MCP 服务端的信任,不是你能评估一次然后存下来的性质,因为工具列表是运行时取回的、并且会在会话之间发生变化。上个周二你信任的那个服务端,是一个今晚就能推送新的工具描述的服务端——而这正是 MCP 工具投毒背后的整套机制。诚实的读法是:那条「可信服务端」豁免覆盖的是你自己构建并部署的第一方服务端,而目录里的东西几乎一个都不覆盖。

如果你能在自己的审批、日志或重试逻辑里,把 readOnlyHint 这个字符串找到任何一处是当作条件、而不是当作展示值使用的,那你就有一个服务端控制的开关装在一个客户端侧的控制上。即便你部署里的每个服务端目前都很诚实,这句话仍然成立。

步骤 3激励是倒着的:闭嘴被罚,断言被赏。

把悲观默认值与「不可信输入」这条规则并排放在一起,结果是协议经济学里的一处定价错误。设想两个服务端,提供同一个 delete_record 能力。

服务端 A 很严谨。它的作者读了规范,判断自己无法诚实地刻画每一条代码路径,于是一个注解都没发。于是每次调用都继承 readOnlyHint: false、destructiveHint: true、idempotentHint: false、openWorldHint: true,而一个把交互设计挂在注解上的客户端,会在每一次调用前摆出一个确认弹窗。

服务端 B 断言 readOnlyHint: true。它要么在撒谎、要么是搞错了——是哪一种并不重要,线上格式分辨不出这两者。一个把交互设计挂在注解上的客户端,会悄无声息地把它跑掉。

于是,表现良好的那个服务端吃到了摩擦,做出不可核实断言的那个走上了安静的路,而用户把这个差别体验成「服务端 A 真烦人」。协议里没有任何机制能化解这件事,因为要化解它,就得去核实一项关于「你并没有在运行的代码」的断言。结论不是说默认值错了——它们是对的,把它们反过来会更糟——而是说:由注解驱动的界面会奖励断言,所以这个界面必须不再由注解驱动。

这与上一层工具 schema 与契约里的那个问题是同一个形状。schema 约束的是模型可以发出的参数,可以在本地强制执行,因为校验器在你手上。注解描述的是边界另一侧代码的行为,而本地没有任何东西能核验它。仅仅因为这两者抵达时在同一个 JSON 对象里,就把它们当成同等有约束力,这就是那个错误。

步骤 4把分类建在客户端、在安装时钉死,并用提示去检测漂移。

你想要的那项控制,是一个挂在(服务端身份,工具名)这一对上的风险等级:由你判定、存在你这一侧、被查询的是它而不是注解。这比听起来省事:一个接上来的服务端只暴露不多几个工具,这份分类是安装或审批时的一次性复核,而你正在做的那次复核——读一遍工具列表、判断每一个能对你做什么——本来就是你在给一个服务端授予任何访问权之前该做的事。

注解于是去干两件它真正擅长的活儿。它们预填那次复核,于是人是在修改一份草稿、而不是从一张空表开始。它们还成为一个漂移信号:一个工具的注解自你钉下它之后变过,就意味着它的描述在你眼皮底下被重写过——无论这次改动是一次「抽地毯」还是一次重构,都值得一个告警。

# the hint pre-fills the review and watches for drift; it never decides
def risk_class(server_id, tool):
    pinned = registry.get(server_id, tool.name)
    if pinned is None:
        raise UnreviewedTool(server_id, tool.name)   # fail closed, loudly

    if pinned.annotation_digest != digest(tool.annotations):
        alarm.raise_drift(server_id, tool.name)        # rewritten under you

    return pinned.risk_class                           # yours, not the server's

# WRONG, and it is the default shape of every quickstart:
#   if tool.annotations.readOnlyHint: run_without_confirmation(tool)

有两个细节决定这套东西撑不撑得住。把注册表的键做成一个稳定的服务端身份——一个端点加一个钉死的包摘要,而不是显示名称,因为显示名称同样由服务端控制。以及:对一个未复核的工具要失败拦截,而不是回落到默认值;回落正是一个新出现的工具如何悄悄拿到那个悲观等级、拿到一个确认弹窗、被用户一路点过去批准掉、然后永远不被复核的路径。那条路通向审批与确认交互设计讲的那种橡皮图章式批准,而闸门的存在是为了被读,不是为了被挥走。

步骤 5重试层是服务端断言变成决定的第二个地方,而没人在看它。

审批闸门之所以受到关注,是因为它看得见。同一个 bug 更安静的那个实例住在你的重试策略里,而它可以说更糟,因为它开火时房间里没有人。

一项看起来挺合理的优化:当 idempotentHint 为真时重试一次超时的工具调用,为假时抛出错误。这个提示是服务端断言的,所以这是一种「由远端一方来设定你的重试行为」的配置。如果那个断言是错的,一次超时就会让一个非幂等的写执行两遍——而超时恰恰是你看不出第一次尝试到底有没有提交的那种情形。两笔扣款、两张工单、两条发出去的消息。

重试决定的正确来源,和审批决定的正确来源是同一个地方:你自己的分类,外加一套让这个问题根本不成立的机制。发一个由你生成的幂等键,让对面照它去重——这就是幂等性与重试里的纪律——你于是不再需要相信关于这个工具内部的任何事。一个遵守了你那个键的服务端,是把幂等性演示出来了,而不是声称了一下。只要哪里有一个提示在承重,这就是可用的通用招法:把一项你无法核验的断言,换成一套让这项断言无关紧要的协议。

openWorldHint 是唯一一个「照提示行事大体无害」的注解,因为它买来的东西不是安全。一个会去碰第三方的工具,带着你控制不了的延迟与你修不了的失效模式,所以这个提示对超时预算有用、对把计划排序成「不确定的调用先发生」有用、对成本估算有用。在它上面搞错,代价是一个糟糕的估算。在 readOnlyHint 上搞错,代价是一条被删掉的记录,而这两者不该共用同一条代码路径。

三项改动,按顺序来。第一,把你客户端里每一处对注解的使用都 grep 出来,分成展示与决定两堆;落在「决定」那一堆里的每一项都是 bug,包括重试那一项。第二,加一份以(端点、包摘要、工具名)为键的注册表,里面放你指派的风险等级,让安装器用注解去预填它,并对任何未复核的东西失败拦截。第三,在钉下的那一刻对注解做哈希,并在其变化时告警——这大约十行代码,是提示的唯一一种用法是敌对服务端无法反过来利用的,而且它抓得住那次工具描述重写,而你栈里没有任何别的东西在找它。然后继续把这些提示显示在界面上,因为一份好的工具描述仍然是让模型调对工具的那个东西,而一套没人展示的风险词汇帮不了任何人。