去年冬天给一个内部客服系统接工具,上线第一周退款成功率只有六成出头。我第一反应是模型不行,换成更强的模型,涨到七成;补了几条 few-shot,涨到七成五,然后卡死了。

真正解决问题的是一个下午的笨功夫:把 refund 这个工具的 description 从头重写了一遍,补上「什么时候不该用它」和「金额单位是分」。同一套代码、同一个模型、同一个 prompt,成功率到了九成四。

那天之后我对工具设计的态度变了。以前我把它当接口文档写,写给同事看的;现在我知道它是 prompt,写给模型看的,而模型不会追问你「这个参数到底什么意思」,它只会按自己的理解填一个看起来合理的值。

一、工具描述是常驻上下文,不是注释

模型能看到的世界只有上下文。它不知道你的系统里有什么表、refund 背后连着哪个服务、失败会怎样。它全部的信息来源,就是那几百 token 的工具定义。

这句话有两个推论,都挺贵。

第一,工具定义是常驻的。它不是调一次才出现一次,而是每一轮推理都在窗口里。五十个工具、每个四百 token,就是两万 token 的固定开销,跑一百轮就是两百万 token 的输入。这笔钱不管你用不用都在付。

第二,描述写得含糊,模型不会报错,它会猜。人类接手一份含糊的接口文档会去问人;模型不会,它会挑一个最像的参数值填进去,然后在你不知情的情况下产生一次错误调用。错误调用的代价远不止这一次请求:错误结果进了上下文,后面几轮都在错误的前提上推理。

所以工具描述这件事的性价比极高——它是最便宜、最可控、见效最快的一环。写一段好的 description,可能比换一个更贵的模型更有效。

一次错误调用的连锁成本,值得单独算一遍。假设模型把 amount 理解成元,实际要的是分,于是传了 199 而不是 19900。这一轮失败之后,程序回灌一条错误,模型看到错误,重新构造参数,再发一次。看起来只是多了一轮,实际上这一轮带着完整的工具结果历史重跑了一遍推理,而且它有可能在第二次仍然理解错——因为它对「为什么错」的理解,完全取决于你那条错误信息写得够不够清楚。一个小歧义,可以吃掉三到五轮。

二、一个工具定义由三部分组成

不管是直接写 JSON schema,还是用 MCP 从函数签名自动生成,落到模型眼前的都是三块:名字、描述、参数。

name:用来区分,不是用来概括

名字的首要职责是让模型在几十个工具里一眼分出来该选哪个。所以:

  • 用「动词 + 宾语」,search_orders 好过 order,cancel_order 好过 order_action。
  • 工具多了以后加命名空间前缀,orders.refund、orders.cancel、billing.refund。这三个如果都叫 refund,模型只能靠描述猜,而描述又长又容易被压缩掉。
  • 避开 process、handle、manage、do、execute 这类空动词。它们不携带任何区分信息,等于把选择压力全部推给 description。

description:回答六个问题

我现在的标准是,一段合格的 description 必须能回答下面六个问题。缺一个,模型就会在那个维度上自由发挥。

要回答的问题 写得差 写得好
什么时候用 「退款」 用户明确要求退款,且订单状态为 paid 或 shipped 时使用
什么时候不用 无 不要用于查询退款进度(用 orders.get_refund_status);不要用于取消未支付订单(用 orders.cancel)
有什么副作用 无 会产生真实资金流动,调用前必须已获得用户确认
是否幂等 无 同一 order_id 重复调用返回同一笔退款单号,不会重复退款
返回什么 无 返回退款单号、退款金额、预计到账时间
失败长什么样 无 订单不存在返回 NOT_FOUND;已退款返回 ALREADY_REFUNDED,不要重试

第三行那条「副作用」尤其容易被忽略。模型对「这个调用是不是安全」是没有直觉的,它需要被告知。写一句「这是只读操作」或者「这会真的给用户发短信」,能显著改变它的谨慎程度。

负向描述(什么时候不用)的价值常常高于正向描述。正向描述告诉模型「这个工具能干什么」,而模型在大多数时候面对的是「几个工具看起来都能干」。这时候一句「查退款进度请用另一个」,抵得上十句功能说明。

parameters:把猜测空间压到最小

参数这一层后面单独讲,先记住一条:schema 里的 description 和工具描述一样重要,而且更常被忽略。字段名 amount 加不加 _cents,决定了模型是给你 199 还是 19900,这个差别在线上就是一次事故。

长度:省字和省错不是一回事

工具描述要短,这个方向没错,但省字的原则是「删掉不承载决策信息的字」,不是「把话说一半」。

「查询订单」四个字很省,可它没告诉模型任何决策所需的信息:什么条件下该查、查不到怎么办、参数长什么样。这四个字实际上是把成本转移到了模型身上——它会用训练数据里的先验去补全,补出来的东西和你系统里的约定十有八九对不上。

反过来,一段两百字的描述里如果有一百五十字在讲背景故事、讲这个服务的历史、讲业务方的诉求,那才是真的浪费。有用的信息是那些会改变模型行为的信息:边界、单位、副作用、失败形态。判断标准可以简化成一句:这句话如果删掉,模型的行为会不会变?不会变就删。

我见过一些团队为了省 token 把描述压到一行,然后在 prompt 里写「工具参数请参考文档」。模型没有「参考文档」这个能力,它只有上下文。省下的那点常驻开销,最后都以误调和重试的形式还了回去。

三、同一工具的两版描述

把上面的原则落到具体代码上,对比最清楚。这是一个电商退款工具。

写得差:

1
2
3
4
5
6
name: refund
description: 退款
parameters:
order: string, required
amount: number, required
reason: string, required

问题一眼能数出来:refund 到底退什么,退给谁;order 是订单号还是订单对象,什么格式;amount 单位是元还是分,能不能超过实付;reason 是自由文本还是枚举;重复调用会怎样;失败会怎样。全部空白。

写得好:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
name: orders.refund
description: |
对已支付的订单发起退款。仅当用户明确要求退款,且订单状态为
paid 或 shipped 时使用。

不要用它查询退款进度(用 orders.get_refund_status);
不要用它取消未支付订单(用 orders.cancel)。

该操作会产生真实资金流动,调用前必须已获得用户确认。
同一 order_id 重复调用是幂等的,返回同一笔退款单号。

parameters:
order_id:
type: string
required: true
description: 订单号,形如 SO 加 12 位数字,例如 SO202611210001。
不是支付流水号,也不是用户 ID。
amount_cents:
type: integer
required: false
description: 退款金额,单位「分」,正整数,不得超过订单实付金额。
省略表示全额退款。
reason:
type: string
required: true
enum: [damaged, wrong_item, not_received, user_request, other]
description: 退款原因,必须取枚举值之一。
reason_note:
type: string
required: false
description: 当 reason 为 other 时必填,20 字以内。

改动其实只有五处,但每一处都对应一类线上事故:

  1. 加了命名空间,把「退款订单」和「退款账单」在名字层面区分开。
  2. 加了负向边界,堵住最常见的两种误调——把查进度当退款、把取消当退款。
  3. 声明了副作用和幂等性,模型才知道什么时候该停下来问用户。
  4. 把单位写进字段名(amount_cents 而不是 amount),这是最省事的一种防错设计,比在描述里解释「单位是分」更可靠,因为字段名一定会被读到,描述可能被截断。
  5. 该枚举的枚举,该给示例的给示例。SO202611210001 这个例子让模型知道该复制什么形状,而不是自己编一个 18 位数字。

四、粒度:一件事一个工具

工具拆分没有标准答案,但有两个明确的反模式,都踩过。

拆得太细。曾经有个文件工具集:list_dir、stat_file、read_file、read_file_range、count_lines、file_exists。看起来每个都很原子,实际上「看一下这个模块的入口在哪」这句话,模型要连着调四次。四次意味着四轮往返、四次完整上下文重发。如果上下文是六万 token,光这一个问题就烧掉二十四万输入 token。而且中间任何一步失败,前面的结果全白费。

合得太粗。另一个极端是万能工具:db_query(sql),或者 http_request(url, method, body)。参数空间是无限的,模型没法可靠地把业务意图翻译成正确的 SQL 或 URL。它一定会写错表名、编造字段、把 POST 写成 GET。粗粒度把「选择工具」的难题换成了「构造参数」的难题,而后者往往更难。

我的判据是这两条:

  • 一次调用应该对应一个模型能独立判断对错的原子动作。 「读这个文件」它能判断对错,「先分析架构再决定改哪」它判断不了。
  • 输入必须能由当前上下文可靠构造出来。 如果模型需要先猜一个 id 才能调用,那说明少了一个前置工具,或者这个 id 应该由程序注入而不是让它填。

按这个标准,read_file 配一个可选的 offset/limit 就够,不必拆成两个工具;而「读文件」和「写文件」必须分开,因为一个是只读一个是副作用,风险等级完全不同。

粒度还会反过来影响工具数量。工具少而粗,选择容易但参数易错;工具多而细,参数简单但选择和轮数成本上升。没有免费的午餐,只能按任务分布调。

五、参数设计:不要让它猜

参数设计的目标只有一个:把模型需要猜的东西减到零。每留一个隐含约定,就多一个线上随机失败点。几条按重要性排序:

枚举优于自由文本。 任何取值集合有限的字段都应该是 enum。status 如果允许 paid/shipped/closed,就别用 string。自由文本的问题不是模型写不出来,而是它写出来的东西你不知道怎么处理——已支付、PAID、paid 都合法,你的 if 判断只认一个。

id 优于自然语言引用。 用户说「把上次那个订单退了」,如果工具要的是 order_id,模型手上没有,它就会编一个看起来像订单号的字符串。正确的做法是:要么先用 search_orders 拿到真实 id,要么把 id 从上游系统直接注入到参数里,不让模型经手。凡是模型「复述」过的标识符,都有被改写一位的风险。

必填与默认值要分明。 能由服务端决定的就别让模型填。currency 默认 CNY、page_size 默认 20,这些字段出现在必填里只会增加出错面。反过来,真正影响业务结果的字段(退多少、退给谁)必须必填,不要给一个「合理默认」——默认猜错比报错更贵。

单位和格式显式声明。 金额用分还是元、时间用 ISO 8601 还是时间戳、时区是本地还是 UTC、分页用 offset 还是 cursor。这类约定在人类文档里都要加粗,在 schema 里更不能省。我现在的习惯是把单位直接编码进字段名:amount_cents、timeout_ms、created_after_iso。名字比注释更难被忽略。

参数别超过五到七个。 超过这个量,模型漏填和填错的概率明显上升。真需要那么多,通常意味着这个工具该拆,或者其中几个应该合并成一个结构化的对象——但结构化对象也有代价,嵌套层级深了模型容易漏字段,两层以上就要谨慎。

避免「要么 A 要么 B」的隐式依赖。 比如 reason=other 时 reason_note 必填。这种条件必填如果只写在文档里,模型八成会漏。可行的做法是在描述里明确写出来,或者在服务端做校验并返回可读的错误提示(下一节讲)。

还有一层容易被跳过:schema 只是声明,不是约束。除非你用严格模式在解码层卡死,否则模型完全可能输出一个 type 正确但语义不对的值——page_size: -5、status: "paid "(带尾空格)、order_id: "unknown"。schema 校验能挡住类型和枚举,挡不住语义,所以业务侧的正则、范围、存在性校验一个都不能少。我的习惯是把它当成「面向不可信输入」来写,而不是「面向自家前端」来写;模型不是一个你可以信任的调用方。

六、返回值是给模型读的,不是给程序读的

这一条我理解得最晚,但影响最大。

传统的 API 设计里,返回值是给程序消费的:字段齐全、类型严格、不做取舍,让调用方自己挑。但工具返回值的第一读者是模型,第二读者才是最终用户。模型要做的事是「读懂这段结果,然后决定下一步或者写一句话给人」。

这意味着三件事:

精简。 数据库查出来四十个字段,模型只需要六个。剩下的三十四个不是「信息更丰富」,是噪声——它们占 token、稀释注意力、还可能诱导模型抓着无关字段做文章。程序侧该裁就裁。

结构化。 返回稳定的 JSON,而不是一段人类可读的散文。散文看着友好,实际上模型要再解析一次,既浪费 token 又容易理解偏。字段名要稳定,{"status": "shipped"} 比 {"当前状态": "已发货"} 更好处理。

带摘要和下一步提示。 长结果在顶部放一句 summary,尾部放一句 next_hint。这不是给程序用的,是给模型用的导航。

截断和分页尤其要说清楚「还有多少没显示」。这是最容易被忽略、后果最严重的一点:如果工具返回了前二十条就停了,却不告诉模型总数,模型会默认这就是全部,然后给出一个自信的错误结论。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
def shape_orders(rows, total, cursor):
return {
"summary": f"共 {total} 笔订单,本次返回 {len(rows)} 笔",
"items": [
{
"order_id": r["id"],
"status": r["status"],
"amount_cents": r["amount"],
}
for r in rows
],
"truncated": total > len(rows),
"next_cursor": cursor if total > len(rows) else None,
"next_hint": (
"还有更多结果,用 next_cursor 继续取;"
"如果只需要汇总数字,直接用 summary.total 即可,不必翻页。"
),
}

truncated 和 next_hint 这两行,成本不到三十 token,但能挡掉一类非常典型的错误:模型看到一个不完整的列表,把它当成完整列表,然后告诉用户「你总共只有 20 笔订单」。

大结果的处理,我一般按三种策略选,取决于模型接下来要拿它做什么:

场景 策略 具体做法
只需要一个结论 程序侧算完再给 不让模型看原始数据,直接返回 {"count": 187, "sum_cents": 4213000}
需要逐条判断 分页 + 明确的剩余量 每页 20~50 条,返回 total、next_cursor、truncated
需要全文但很长 摘要 + 可展开的引用 先给结构与摘要,标注 detail_ref,模型需要时再调用详情工具

第一种最容易做错。很多人习惯「把数据都给模型,让它自己统计」,觉得这样更灵活。但模型数数是弱项,一百条以上的求和、去重、比较几乎必错,而且你无法从结果上看出它错了。能在 SQL 里 GROUP BY 出来的东西,不要交给概率模型数。

第二种的关键是「明确的剩余量」。除了 total,我还会在 summary 里用人话写一句「共 187 笔,本次返回 20 笔」,因为结构化字段有可能被模型忽略,而一句自然语言很难被忽略。

第三种是渐进式披露在工具层的用法。返回一个目录结构加每个条目的 token 估算,让模型自己决定往下钻哪一支。这比一次性把整棵树塞进去省得多,也更符合「先看索引再读正文」的检索习惯。

七、并行与串行:轮数就是钱

工具调用有两种时序:可以并行的和必须串行的。

可以并行的:彼此没有数据依赖的调用。读三个互不相关的文件、查三个城市的天气、给五个订单分别查物流。这类调用如果模型支持并行工具调用,一次就能发出去,一轮拿回全部结果。

必须串行的:后一个调用的参数依赖前一个的结果。典型的是「先列目录再读文件」——不先 ls,就不知道路径。还有「先查订单拿到 user_id,再查用户详情」。

区别在于轮数。每一轮都是一次完整的上下文重发:模型带着全部历史重新推理一遍。所以串行的真实成本不是「多调一次接口」,而是「多付一遍上下文」。上下文六万 token、串行四轮,就是二十四万输入 token 的额外开销,还不算延迟。这一点在上下文工程那篇里算过一笔账,工具设计是它最大的一个杠杆。

由此有两条优化方向,都很实用:

能合并的合并。 get_orders(ids: string[]) 比循环调 get_order(id) 好一个数量级,因为它把 N 轮压成一轮。批量接口在 Agent 场景里的收益远高于普通后端场景,因为这里省的是上下文而不是网络往返。

让一次返回足够后续使用。 search_orders 除了 id 和状态,顺手把 user_id、amount、created_at 一起返回。这样后续大多数分支都不用再查详情。多返回三个字段的成本,通常远低于多跑一轮的成本。

反过来说,如果发现某个任务总是串行五六轮,先别急着优化模型,去看看工具集里是不是缺了一个「一次给够」的接口。

举一个真实的任务:「把这五个订单的物流状态查一下,超时的标出来」。最差的实现是循环五次 get_logistics(order_id),五轮。稍好一点是一次并行发五个调用,一轮拿回。最好的是有一个 get_logistics_batch(order_ids),一轮一次调用,而且服务端可以在内部并发。三者的模型侧复杂度依次下降,而成本差不多是五比一比一。差别不在接口本身有多难写,在于设计工具时有没有想过「这个工具会被连着调很多次」。

还有一点值得提醒:不要为了并行而伪造并行。模型一次发出三个调用,程序并发执行,但结果必须按调用 id 一一对应回灌。对错了位置比串行更糟——模型会拿 A 的结果去解释 B 的问题,而且它自己不会发现。

八、错误返回:让它能自己爬起来

工具一定会失败。网络超时、参数非法、权限不足、资源不存在。失败之后的第一次交互质量,决定了这一轮是「模型自我修正」还是「模型开始瞎编」。

最差的错误返回是这几种:

  • Error: 500
  • 直接抛一段两百行的堆栈
  • 返回 null,什么都不说
  • 把错误当成空结果返回 []

最后一种最阴险。模型看到空数组,会理解成「查了,没有」,而不是「查失败了」。于是它告诉用户「你没有这个订单」,实际上只是数据库连接超时。

结构化的错误返回应该包含四样东西:错误码、人类可读的消息、是否可重试、以及修正建议。

1
2
3
4
5
6
7
8
9
10
{
"ok": false,
"error": {
"code": "INVALID_ARGUMENT",
"field": "order_id",
"message": "order_id 格式不合法:期望 SO 加 12 位数字,收到 \"12345\"。",
"retryable": false,
"hint": "请先用 orders.search 按手机号或下单时间查到真实订单号,再重新调用。不要自己补全订单号。"
}
}

hint 这一行是整段里最有价值的。它把「你错了」变成「你该怎么做」,模型自我修正的成功率差别非常大。特别是末尾那句「不要自己补全订单号」,直接堵住了模型最常见的补救方式——编一个。

错误码要和可重试性绑定,分三类:

类型 例子 可重试 模型该做什么
参数错误 字段缺失、格式不对、枚举越界 否 修正参数后重调,或换工具
业务拒绝 订单已退款、余额不足、无权限 否 停止,把原因转述给用户
暂时故障 超时、限流、上游 5xx 是 退避后重试,超过次数再降级

把这三类混在一起返回(比如统一 {"error": "failed"}),模型只能靠猜,而它倾向于猜「再试一次」——对业务拒绝重试三次,是最常见的无效烧钱方式。

九、工具数量与窗口预算

一个中等复杂度的工具描述,三百到六百 token 很正常。五十个工具就是一万五到三万 token 的常驻开销。放在两百 k 的窗口里看不算致命,但它有三个隐性成本:

工具数 常驻开销 主要问题
5 ~ 10 2k ~ 5k 基本无压力,选择准确率高
10 ~ 30 5k ~ 15k 开始出现「相似工具误选」,需要命名空间
30 ~ 60 15k ~ 30k 选择准确率明显下降,且压缩时容易被挤掉
60 以上 30k+ 单靠描述已经分不清,必须做分组或检索

注意表格最后一行的问题不是钱,是准确率。工具越多,语义越容易重叠,模型误选的概率越高。而误选的代价不只是白跑一次,是把无关结果灌进了上下文。

所以「按需装载」不是省钱技巧,是效果技巧。几种可行做法:

  • 按任务阶段分组:探索阶段只给检索类工具,编辑阶段只给读写类工具。很多 Agent 框架支持动态挂载。
  • 按项目装载 MCP:不用的 MCP Server 关掉。一条 MCP 配置动辄带进来十几个工具,全量常驻很浪费。
  • 工具检索(meta-tool):先给模型一个 find_tools(query),让它描述需求,程序返回匹配的三五个工具 schema,再注入上下文。多一轮,但省下几十 k 常驻开销,工具规模大时是净赚。
  • 合并同质工具:get_user_by_id / get_user_by_email / get_user_by_phone 合成一个 get_user(by, value),减少的是选择面,不是能力。

顺带一个和缓存有关的细节:工具定义的顺序会影响前缀缓存。工具清单一般放在上下文前部,一旦你中途增删一个工具,它后面的缓存全部失效。所以在做「按需装载」时,尽量按稳定的分组切换(比如整组检索工具一起上、一起下),而不是每轮都微调,否则省下的 token 又被缓存失效吃回去。

常见的坑

  • 把工具描述当注释写。 一行「查询订单」配三个裸参数,然后奇怪为什么模型总填错。描述是 prompt,不是文档。
  • 参数名不带单位。 amount、timeout、size 这类名字,模型会按训练数据里最常见的单位猜,猜中纯属运气。
  • 返回值原样透传。 把上游 API 的完整响应塞进上下文,四十个字段里三十四个是噪声,还顺手把内部字段名暴露给了模型。
  • 截断但不声明。 返回前二十条就停,不说总数也不给 cursor,模型会当成全集下结论。
  • 错误信息里带堆栈。 几百行堆栈进上下文,模型抓不到重点,还可能是它读得最认真的部分。
  • 业务拒绝当成可重试。 订单已退款这种确定性失败,重试三次只会让用户多等三十秒。
  • 工具拆得过细。 一个简单问题串五六轮,成本翻几倍,中途失败的概率也翻几倍。
  • 为了并行把结果对错位。 三个并发调用返回后按数组下标硬对应,一旦某个失败整体错位,模型会拿着 A 的结果解释 B。
  • 工具全量常驻。 装了一堆 MCP 却不关,每轮都在为几十份说明书付费,还要承担误选风险。

检查清单

  • 每个工具的 description 都能回答六个问题:何时用、何时不用、有无副作用、是否幂等、返回什么、失败长什么样。
  • 工具名是「动词 + 宾语」,工具多了加命名空间前缀,没有 process / handle 这类空名。
  • 取值有限的参数一律用枚举,不用自由文本。
  • 金额、时长、尺寸这类带单位的字段,单位写进字段名。
  • 任何需要模型「复述」的标识符,先确认它是不是能从工具拿到真实值,拿不到就别让它填。
  • 返回值只保留模型需要的字段,顶部有 summary,长结果有 truncated 和 next_cursor。
  • 错误返回带 code、message、retryable、hint,四样齐全。
  • 检查任务的平均轮数,超过五轮就找找是不是缺一个批量接口。
  • 算一次工具常驻开销,超过一万五千 token 就做分组或按需装载。
  • 上线前用一个真实任务跑一遍,看模型在参数上猜了什么——它猜的地方就是你描述没写清的地方。

工具设计是 Agent 工程里少有的「投入产出比接近线性」的环节:你多写一句边界,模型就少一次误调;你把单位放进字段名,线上就少一类事故。它不需要换模型,也不需要改架构,只要求你换一个视角——把接口文档当成 prompt 来写。

这件事的难点不在技术,在于克制:忍住不写「什么都能干」的万能工具,忍住不把上游返回原样透传,忍住不用一句「查询订单」打发掉本该写清楚的三百字。真正写好的工具描述,读起来像一份给新同事的操作手册,而不是一份给编译器的类型声明。

系列大纲与全部篇目见:Agent 原理与开发。

延伸阅读