结论先行:对模型来说,工具的名称和描述就是接口文档加使用说明书,也是它决策的唯一依据。工具设计是 API 设计与文档写作的复合体——命名、描述、参数、返回值每一项都直接影响调用成功率。工具描述的质感,就是你 Agent 能力的上限。
命名:一个工具做一件事
命名原则和设计 REST API 一样:动词加宾语,get_order_status、refund_ticket。比命名更要紧的是职责边界——两个工具职责重叠时,模型会随机选一个,然后因为参数不匹配而失败。常见的问题形态:
| 命名 / 设计 | 问题 | 改法 |
|---|---|---|
get_data(万能查询) | 什么都能查等于什么都查不准 | 按业务对象拆分成专用工具 |
query_order 与 get_order 并存 | 职责重叠,模型随机选 | 合并为一个,或在描述里写明互斥 |
order_no 参数实际可传手机号 | 语义与实现不符,格式填错 | 拆成专用工具,各管各的入参 |
tool1、final_tool | 无语义,纯靠猜 | 动词加宾语,见名知意 |
反例展开说:get_data(什么数据都能查)配 query_order(查运单),模型分不清该用哪个。改法:按业务对象切分工具,每个工具在描述里写清楚"什么时候不用我"。工具数量多时,命名还承担检索职能:模型面对几十个工具会先按名称和描述粗筛候选,带业务前缀的命名(logistics_get_order)让同域工具天然聚簇,粗筛准确率更高——和代码里按模块组织函数是同一个道理。
描述:写四件事
合格的工具描述包含:做什么、什么时候用、什么时候不用、参数与返回的语义。下面这个对比来自常见的踩坑模式——差的描述只是函数名的复读:
{
"name": "get_order",
"description": "查询运单",
"parameters": {
"type": "object",
"properties": {
"order_no": {"type": "string", "description": "单号"},
"date": {"type": "string", "description": "日期"}
}
}
}
问题:模型不知道 order_no 的格式、date 是否必填、能不能用手机号查。同一个工具合格的写法:
{
"name": "get_order",
"description": "按运单号查询运单的状态、司机与费用信息。仅支持精确运单号查询;用户只提供手机号或姓名时不要调用本工具,改用 search_order_by_customer。运单号格式为 FY 开头加数字。",
"parameters": {
"type": "object",
"properties": {
"order_no": {"type": "string", "description": "运单号,FY 开头,如 FY20251209001"},
"with_fee": {"type": "boolean", "description": "是否返回费用明细,默认 false"}
},
"required": ["order_no"]
}
}
描述里的"什么时候不用我、改用谁",是对付模型选错工具的最便宜手段。注意描述最终会占上下文,控制在几句话内,信息密度优先——每一句都要能改变模型的调用行为,不能改变行为的话删掉。描述写完有个便宜的验收方法:让一个不知道该工具的模型只读名称和描述,写出它认为的调用方式和典型场景,与你的预期对照,偏差就是描述的缺口。这个方法五分钟一轮,比等线上 badcase 便宜得多。
参数:少、明、枚举化
三个规则。参数尽量少:超过五六个模型填错率明显上升,先砍非必要参数——不是每个后端接口参数都值得暴露给模型,很多可以用默认值收进工具内部。语义要说死:“日期"必须写清是下单日还是发货日、格式是什么(“下单日期,ISO 8601 格式 YYYY-MM-DD”),语义含糊的参数是参数填错的最大来源。取值有限的一律用枚举,别让模型自由发挥字符串:“优先级"给 high|medium|low 的枚举,比"写一个优先级描述"可靠得多。
复杂场景宁可拆成多个简单工具(先搜索拿 ID,再按 ID 查详情),也不要一个吃十种参数的巨型工具——巨型工具的每个参数组合都是一次填错机会。参数设计还有向后兼容的考量:新增参数给默认值,旧轨迹里的调用不失效;语义变更等于破坏性变更要走迁移。工具一旦被 Agent 稳定调用,它就是有用户的线上接口,API 演进的纪律一样适用。
返回值:为模型裁剪,让错误可行动
返回值不是数据库实体的序列化,而是为当前决策定制的信息:只留模型会用到的字段,30 字段的实体裁到 5 个。错误信息尤其重要——错误是给模型看的修正提示,不是给运维看的堆栈:
# 差:"Error: duplicate key violation",模型不知道能做什么
# 好:模型读完就知道下一步做什么
{"error": "order_no_not_found",
"message": "运单号 FY20251209 不存在,疑似少了一位数字",
"hint": "请向用户确认完整 13 位运单号后再调用"}
hint 字段是返修率最低的投资:一句话告诉模型下一步动作,胜过它三次盲目重试。返回值裁剪还有一个常被忽略的收益——裁剪后的返回值进入上下文,直接决定后续轮次的注意力质量,这和上下文工程是同一件事。列表类返回要防全量倾泻:“查所有运单"返回上千条会把上下文打穿,设计成"默认前 N 条 + 总数 + 翻页工具”,把翻页的决定权留给模型按需使用。
迭代方式:用调用成功率驱动改进
工具调用成功率就是工具设计的评估指标。从评估集里统计三类数字:选错工具的比例(改描述,尤其是补"什么时候不用我”)、参数填错的比例(改参数设计,语义说死、枚举化)、结果没被利用的比例(改返回值裁剪)。工具层的三处小改动,经常比换模型对整体准确率的贡献更大——因为换模型解决不了"接口文档本身写得含糊"的问题。三类数字的统计有现成的取数点:审计日志里工具名与用户意图的对照给选错率,Schema 校验的失败日志给参数填错率,对照最终回答引用了返回值哪些字段给利用率。三个数字按月看趋势即可,重要的是归因到具体工具再动手——全局平均数会把个别烂工具藏起来。
实战场景
查询工具的 date 参数是典型翻车点:描述只写"日期”,模型有时传下单日有时传发货日,同一个问题答案不稳定,评估集里一批参数填错类 case 反复红。三步修完:参数描述写死语义与格式(“下单日期,ISO 8601,YYYY-MM-DD”);把"按手机号查"从 get_order 里拆出去,独立成 search_order_by_customer,并在 get_order 描述里写明"仅支持精确运单号,手机号请改用某某";返回值按模型实际使用的五个字段做白名单裁剪。改完从评估集重新统计三类数字:选错工具的 case 在描述补上互斥说明后消失,参数填错 case 被语义说死压下去,剩下的失败集中在模型能力问题——这才轮到考虑换模型。这个排查顺序值得记住:先怀疑接口文档,再怀疑模型。工具层改动的另一个好处是生效即时——改描述、改参数下次请求就生效,不像换模型要重跑全部回归,迭代节奏完全不同。
检查清单
- 命名动词加宾语,一个工具做一件事,无万能查询工具
- 职责相邻的工具在描述里互相声明边界与替代品
- 描述覆盖四件事:做什么、何时用、何时不用、参数语义
- 参数个数控制在五六个以内,非必要参数收进默认值
- 参数语义说死:业务口径加格式,取值有限一律枚举
- 返回值按模型需要裁剪,不回传全量实体
- 错误返回"错误码 + 一句话说明 + hint",hint 给出下一步动作
- 用评估集统计选错工具、参数填错、结果未利用三类比例驱动迭代