模型调错工具的锅,八成在 schema 上:工具定义设计实战

📅 2026/11/15 ✍️ 小文 📖 约 1 分钟

同一个模型,工具调对率能从 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, ...),参数里用枚举区分动作。参数错了能重试,工具选错了整个流程就歪了。

一套可执行的检查清单

上线前,对每个工具问五个问题:

  1. 参数里有自由字符串可以换成枚举吗?
  2. 描述里有”什么时候不要用”吗?
  3. 错误返回是否包含修正建议?
  4. 当前可见工具数是否 ≤ 12?
  5. 有没有两个工具,只看描述无法区分?

五条全过,工具层的锅基本就甩给模型了——而如果还有问题,通常是真的模型能力问题,这时候换模型才有意义。

📤 分享到