Function Calling 与工具设计
去年冬天给一个内部客服系统接工具,上线第一周退款成功率只有六成出头。我第一反应是模型不行,换成更强的模型,涨到七成;补了几条 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 | name: refund |
问题一眼能数出来:refund 到底退什么,退给谁;order 是订单号还是订单对象,什么格式;amount 单位是元还是分,能不能超过实付;reason 是自由文本还是枚举;重复调用会怎样;失败会怎样。全部空白。
写得好:
1 | name: orders.refund |
改动其实只有五处,但每一处都对应一类线上事故:
- 加了命名空间,把「退款订单」和「退款账单」在名字层面区分开。
- 加了负向边界,堵住最常见的两种误调——把查进度当退款、把取消当退款。
- 声明了副作用和幂等性,模型才知道什么时候该停下来问用户。
- 把单位写进字段名(
amount_cents而不是amount),这是最省事的一种防错设计,比在描述里解释「单位是分」更可靠,因为字段名一定会被读到,描述可能被截断。 - 该枚举的枚举,该给示例的给示例。
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 | def shape_orders(rows, total, cursor): |
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 | { |
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 原理与开发。
延伸阅读
- 上下文窗口与上下文工程 —— 工具定义是常驻窗口的固定开销,这篇算过这笔账。
- 模型选型与推理参数 —— 工具的边界之外,模型本身的指令遵从同样是分水岭。
