工具都接好了，AI 为什么还总选错

给 AI 接上日历、搜索和预订工具以后，很容易产生一种期待：能力都齐了，接下来应该只是把需求说清楚。

但有时它查房间用了查订单的工具，找空闲时间直接走到了创建预订，明明有专门的查询入口，却绕着通用搜索试了好几轮。每个接口单独测试都能成功，串起来却像一个刚上班、还没认清门牌的新同事。

我觉得这种问题值得先停一下：我们给模型看的说明，究竟讲清了功能，还是只重复了一遍工具名字？“查询信息”“管理预订”“搜索相关内容”，对写接口的人来说可能足够，对第一次接触系统的人却没什么帮助。

工具说明看起来像文档，实际上还承担着导航的工作。模型读到什么边界，会影响它下一步选择哪条路。接口可以测通，导航也应该单独验收。

同样一个“查”，可能通往三扇门

下面用一个假设的共享空间服务贯穿说明，不是实际产品的故障记录，也没有模型实测数据。

这个服务有三个工具：查询房间设施、查询某段时间的空闲房间、查询已经存在的预订。现在用户说：“帮我看看周五下午，有没有能坐六个人、带投影的房间。”

如果三个工具分别叫 search、query、lookup，说明都是“按条件查询相关信息”，选择就变成了猜谜。懂业务的人知道用户要先找可用空间；模型只能从极其接近的文字里推断差别。

把名字改成 rooms_search、availability_search、bookings_search 会好一些，但还没结束。房间搜索到底能不能判断空闲？预订搜索返回的是自己的订单，还是整个场地的占用情况？“周五下午”有没有默认时段？这些条件仍藏在开发者脑子里。

我会先给它们写一句真正有区别的话：房间搜索查容量和设施，不判断某时段是否可用；空闲搜索需要明确开始和结束时间，返回满足条件的可用房间；预订搜索查已经创建的记录，不负责寻找新的空闲位置。

这不是要求说明越长越好，而是让相邻工具之间有一条看得见的分界。最有价值的一句话，往往不是“我能做什么”，而是“遇到这个容易混淆的需求，请用另一个入口”。

Anthropic 在 2025 年的《Writing effective tools for agents》中，把工具说明和评估放在一起讨论：说明应像交接给新同事那样补足隐含上下文，评估则要来自真实任务，而不只是简单调用。它也提醒，名称和分组方式的效果需要实际测试，不能假定某个命名规则对所有模型都最好。官方原文。

我从这里得到的启发是：别把“我们团队都能看懂”当成说明已经合格。团队成员共享的常识，恰好可能是模型没有的那一部分。

名字清楚以后，参数仍然会骗人

假设我们把空闲查询的用途写清楚了，参数却长这样：date、time、number。

number 是人数、房间编号，还是希望返回几条结果？date 是房间所在地的日期，还是用户所在地的日期？time 填“下午”能接受吗？如果工具只认具体时间，模型随手补成两点到四点，接口也许照样返回成功，但用户原本想找的是三点到五点。

这里最难发现的错误，是参数合法而含义错误。类型检查能证明传进来的是一个整数，不能证明这个整数代表用户真正需要的人数。日期字符串格式正确，也不能证明时区选对了。

我会把人数写成 attendee_count，把时间拆成 start_at 和 end_at，明确格式、时区要求和区间规则。如果后端约定结束时刻不计入占用区间，就在说明中给出一个小例子：两点到三点的预订，与三点开始的预订能否相接。是否允许相接仍由服务自己的规则决定，不能让模型凭生活经验补。

示例最适合解释歧义，不适合穷举所有参数。展示一组带时区的完整时间，比写一句“请使用正确时间”有用；说明人数是参与者总数，比连续强调“必须准确”有用。

还要让模型知道缺条件时怎么办。“下午”没有被产品定义成固定区间，就应补问具体时间；已有偏好设置时，可以使用设置，并让用户知道采用了什么。工具说明不应该悄悄创造默认值，默认值应来自真实产品约定。

这也解释了为什么一味在用户提示里补一句“仔细检查”，经常没有解决根本问题。认真不能替代定义。要先把模型无从得知的规则写出来，再谈它有没有照做。

查得到，不代表现在就该订

再改一下用户的话：“帮我看看周五有什么房间，我还没决定。”

一个叫 manage_booking 的工具，如果把查询、创建、修改都塞在一起，模型需要自己判断动作参数。即使文档写了“支持多种预订操作”，它仍然没有告诉使用者：哪些输入只会返回信息，哪些输入会改变现实状态。

对于这个例子，我更愿意把查询和创建分开。查询负责回答有没有，创建负责落实一个明确的选择。创建工具的说明应交代必须具备的房间、时间和参与人数，也要说清楚它会真正占用资源。是否已经获得用户授权，则要结合用户原话和应用规则判断，不能靠参数齐全来推定。

用户说“看看”，即使模型能猜出最合适的房间，也不等于用户要求它下单。相反，用户已经明确说“把这间订下来”，条件也完整，就不该为了显示谨慎反复询问同一件事。

这张分界图说的是产品语义，不是安全机制的替代品。说明书能降低误用概率，真正的权限控制、可用性检查和冲突处理仍要由服务执行。模型可能读错说明，也可能漏看；不允许发生的操作，不能仅靠一句“请勿调用”守住。

同样，创建操作返回失败后，能不能直接重试也必须由实际服务语义决定。请求超时不一定表示预订没建立。如果没有查询结果或可靠的去重机制，盲目再创建可能得到两条订单。说明应该交代恢复入口，后端应该提供能执行的恢复能力，两者缺一不可。

这已经超出改几个工具名字的范围，却正是验收容易暴露的地方：当我们试图把说明写清楚，才发现产品本身的边界还没定下来。

把说明放进选择题，而不是让它自我介绍

工具作者很容易写出这样的测试：“调用空闲查询工具，查周五两点到三点。”这能检查格式，却把最难的选择替模型做完了。

更有用的输入是用户自然会说的话：“周五两点到三点，我们六个人，想找个能投屏的地方。”测试记录里另写预期：应查询空闲，人数为六，设施条件包含投屏，不创建预订。

再放一条看起来很像、答案却不同的任务：“我上次订的六人房是哪间？”这次应查既有记录。两条任务都有“六人”“房间”，但一个面向未来空闲，一个回查历史订单。只有把它们放在一起，才能看出说明有没有帮模型理解对象。

还可以放第三条：“周五下午订一间。”没有确切时段，也没有足够的选择条件。如果测试把“任意创建成功”算通过，就会奖励模型替用户编条件。合理预期应来自产品规则：先补齐哪些信息，哪些已有默认值可用，以及什么时候才允许创建。

验收也不宜把某一条调用顺序写成唯一正确答案。一个系统可能允许先按设施筛房间，再查这些房间的空闲；另一个系统可以一次完成组合查询。只要任务结果正确、没有越过授权边界、没有漏掉必要条件，都可能是合理路径。

所以我会把必须满足的条件和允许变化的做法分开。必须满足的是时间、人数、设施和不擅自创建；可以变化的是先查哪项、是否多做一次核对。这样才能测到使用能力，而不是测模型有没有复刻作者心里的台词。

改了一句以后，怎么知道真的更好了

最直接的办法是保留同一批任务，在尽量一致的模型和设置下，对比修改前后的实际调用记录。记录不必复杂：用户请求、选择的工具、关键参数、返回结果，以及任务最后是否完成。

只看最终回答不够。模型可能先选错、碰壁后绕回来，答案看起来仍然正确；也可能选对工具，却填错时间，最后写出一段流畅解释。前一种意味着额外绕路，后一种意味着结果已经偏离需求，修法不一样。

发现“选错”就检查相邻用途有没有重叠；发现“参数错”就检查名称、单位、时区和例子；发现“缺条件也行动”就检查前置条件与产品默认值。这样修改才有具体目标，不会把每次失败都归结成模型不够聪明。

样本也要留一部分不参与修改。否则我们很容易把说明写成那几道题的答案：某种措辞能过，用户换个说法又失败。留出的任务可以表达相同意图，但使用不同措辞，也可以带上重名房间、跨日时间或没有匹配项的情况。

比较时也要留意工具本身是否可用。若一轮碰上权限不足，另一轮服务正常，完成率差异不能全算在说明头上。把环境失败单独记下来，再看选择和参数是否正确，才能避免修错地方。

小样本通过只能说明这些情况有改善，不能保证所有用户请求都可靠。换了模型、增加了相似工具、改变了默认值，都值得重跑。工具说明和实现一样会变化，验收记录应能对应到当时的版本，不能把很久以前的一次通过永久贴在今天的工具上。

还有一类失败，不能继续靠加说明解决。假设房间查询只认识房间编号，而用户只能说“靠窗那间”；或者空闲工具根本不支持设施筛选，说明却要求模型精确查出带投影的房间。此时缺的是数据或能力。把文档写成一页操作守则，也不会让不存在的字段出现。应先补上可查的信息，或明确告诉用户目前只能完成到哪一步。

我也不愿把每次误用都变成一条永久禁令。今天多加一句“不要查订单”，明天又加一句“必须先查房间”，最后可能连回查旧订单这种正常需求也被挡住。更稳妥的做法是找到判断依据：用户要找的是历史记录，还是未来可用资源？将这条依据写到相邻工具的边界上，再同时检查正例与反例。说明的质量，不在于禁止了多少事情，而在于正常任务有没有清楚的去处。

普通使用者即使改不了工具，也能保留两三条经常出错的原始请求，连同错选的入口反馈给维护者。这比一句“你们的 AI 不太聪明”更容易推动修复：问题发生在哪个分岔口，已经有了可复现的材料。

我现在会把工具接入看成两件事：先让动作确实能够执行，再让使用者知道什么情况下执行它。前一件靠接口测试，后一件靠有区别的任务来检查。工具说明写得再顺，也只有经过实际选择，才知道那块门牌有没有把人带到正确的房间。