模型调错工具的锅,八成在 schema 上:工具定义设计实战
同一个模型,工具调对率能从 62% 提到 94%,差别只在工具定义怎么写。本文拆解参数设计、描述写法、错误信息与工具数量的四条硬规则。
团队里最常见的误判是:“模型不稳定,换个更强的模型就好了。”
我们最近做过一组对照实验:同一套 12 个工具的 Agent,同一个模型(不换),只改工具定义(schema 与描述),任务成功率从 62% 提升到 94%,平均工具调用轮数从 4.7 降到 2.9。模型没变,工具没变,变的只是”怎么写给别人看”。
这件事的底层逻辑很简单:模型对工具的认知,100% 来自你写的那段 schema 和描述。 它没有任何额外信息。你写得含糊,它就只能猜。
规则一:参数宁少勿多,宁枚举勿自由
最常见的坏设计,是照搬后端接口的参数表:
{
"name": "query_orders",
"parameters": {
"type": "object",
"properties": {
"user_id": {"type": "string"},
"status": {"type": "string"},
"start_date": {"type": "string"},
"end_date": {"type": "string"},
"page": {"type": "integer"},
"page_size": {"type": "integer"},
"sort_by": {"type": "string"}
},
"required": ["user_id"]
}
}
七个参数,模型至少要正确决定四个。status 是自由字符串,它能猜到 paid、已支付、PAID_ 里哪个才对吗?start_date 的格式是 2026-01-01 还是时间戳?
改成这样,调对率立刻不一样:
{
"name": "query_orders",
"parameters": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": ["paid", "pending", "refunded"],
"description": "订单状态;不确定时不要传,默认返回全部"
},
"time_range": {
"type": "string",
"enum": ["today", "last_7_days", "last_30_days", "all"],
"description": "时间范围。用户说'最近'时用 last_7_days"
}
}
}
}
要点三条:能枚举就不自由(枚举值把决策空间从无穷收缩到 3)、能不给默认就不给(可选参数让模型自己做取舍)、不要暴露分页参数(模型不该关心分页,由实现层循环补齐)。
规则二:描述写”何时用”,不写”是什么”
开发者习惯写:“查询订单信息。” 这是给人类看的文档。模型需要的是决策依据:
用户在问”我的订单到哪了""帮我查一下上周买的东西""退款进度”时使用。不要用它查商品库存(用
check_stock),也不要用它查物流轨迹(用track_shipment)。
多写一句”不要用它做什么”,效果经常超过加一百个 token 的示例。因为模型的主要失败模式不是不会用,而是用错了工具。
工具之间的边界,必须在描述里显式对立起来。两个功能相近的工具,如果不写清”什么时候用 A 不 用 B”,模型的选择基本是随机的。
规则三:错误信息要写给人看,也就是写给模型看
后端习惯返回 {"code": 40012, "msg": "invalid param"}。模型看到这行,只能重试同样的调用。
改成这样:
{"error": "start_date 不能晚于 end_date。你传入的 start_date=2026-11-10,end_date=2026-11-01。"}
模型下一次调用几乎必然自愈。错误信息是 Agent 的自我修正指令,不是给运维看的日志。为工具设计一套”面向模型的错误语言”,是投入产出比最高的一次改造。建议每个错误都包含三件事:错在哪、为什么错、怎么改。
规则四:工具数量超过 12 个,必须分组或收窄
工具越多,选错的概率越高,这个关系大致是超线性的。超过 12–15 个工具后,我们观察到两个现象:
- 检索型工具(查询、搜索)开始被误用为执行型工具;
- 模型倾向于反复调用同一个熟悉工具,而不是尝试正确的那个。
解法不是硬塞更多工具,而是收窄当前可见的工具集:按对话阶段动态挂载(前 3 轮只给”信息收集”类工具),或者用一层”工具路由器”——先用一个小模型把用户意图分到 3–4 个工具组,再挂载该组的工具。
另一种有效手段是合并同质工具:create_ticket、update_ticket、close_ticket 三个工具,可以合并成 manage_ticket(action, ...),参数里用枚举区分动作。参数错了能重试,工具选错了整个流程就歪了。
一套可执行的检查清单
上线前,对每个工具问五个问题:
- 参数里有自由字符串可以换成枚举吗?
- 描述里有”什么时候不要用”吗?
- 错误返回是否包含修正建议?
- 当前可见工具数是否 ≤ 12?
- 有没有两个工具,只看描述无法区分?
五条全过,工具层的锅基本就甩给模型了——而如果还有问题,通常是真的模型能力问题,这时候换模型才有意义。