大模型总调错工具？教你写好工具说明

在开发 AI 智能体时，你是否遇到过这样的场景：明明定义了多个工具，但大模型总是选错工具，或者填入错误的参数？这往往不是模型能力的问题，而是 Tool Schema（工具模式） 写得不够清晰。

Tool Schema 不仅是后台程序检查数据格式的契约，更是大模型理解工具用途和使用限制的关键依据。一份优秀的工具说明，能直接决定模型能否准确选对工具并填对参数。

工具命名：拒绝模糊，明确业务语义

工具的名称是模型识别功能的第一入口。如果名称过于泛化，模型很难区分相似功能。

反面案例：

• 工具 A：查询信息
• 工具 B：获取数据

这两个名字太泛了，模型很难判断在特定任务下该调用哪一个。

正面案例：

• 工具 A：按订单编号查询发货状态

通过明确业务场景，模型的角色空间一下子就清晰了。当然，工具名称也不能无限拉长变成一句完整的话，关键的业务语义可以进一步放入参数的具体描述和使用条件中详细展开。

参数定义：超越数据类型，明确来源与边界

在定义参数时，仅标明基本类型（如字符串、数字）是远远不够的。以“订单编号”为例，如果类型仅定义为 string，模型无法区分它是：

• 订单的业务编号？
• 用户的身份编号？
• 还是数据库里的内部记录编号？

最佳实践建议：

1. 明确来源：详细说明编号应当从哪里来。例如，能否用前端页面展示的编号代替底层内部编号？
2. 处理缺失值：如果字段不存在，应如何处理？
   • 场景：用户在对话中只提供了手机尾号。
   • 错误做法：为了满足必填项要求，随意编造一个值。
   • 正确路径：
     • 调用另一个合法的查询步骤，通过手机号定位完整订单编号；
     • 或在对话中请求用户补充完整的订单信息。

关键在于，不能为了填参数而随便乱补一个值进去。

返回结构：区分业务状态，避免误导模型

工具的返回结构同样重要，但常被忽略。在业务逻辑中，“没有找到订单”和“查询服务暂时不可用”是两码事。

设计原则：

• 状态明确：应当给不同情况返回不同的、能让模型明确识别的状态码或消息。
• 避免歧义：如果模型只看到一个空结果，它很可能误以为业务对象本身不存在，从而给用户错误的回答。
• 权限处理：遇到权限不足时，需在返回结果中明确表达。
• 安全细节：在返回错误信息时，不要泄露用户原本不该看到的对象详情。

错误信息的目标： 指导模型接下来该怎么做（例如：换个查询条件，或向用户说明情况），而不是只留下一句光秃秃的“调用失败”。

验收方法：人类可读性测试

如何验收工具说明写得好不好？有一个非常实用的做法：

1. 人类盲测：让同事只看工具描述，完全不看底层代码实现，判断面对同一个任务时该调用哪一个工具。
2. 逻辑判断：如果连人类工程师看了描述都分不清，那就别指望模型能稳定猜对。
3. 边界测试：在人能分清后，再用缺少参数的用例、功能相似的工具或越界输入进行压力测试。

重要提醒：Schema 不是安全校验的替代品

虽然写好 Schema 能很大程度上减少模型理解的歧义，但这并不是安全校验的替代品。

即使模型严格按照契约传了参数，服务端的实际业务代码里，依然要老老实实地验证：

• 参数的合法性
• 用户的权限

一个真正可用的工具契约，应当是同时照顾到模型对语义的理解以及底层程序执行的严谨性。

总结

写好 Tool Schema 的核心在于：

• 命名清晰：体现业务语义，避免泛化。
• 参数详尽：明确来源、类型及缺失处理逻辑。
• 返回明确：区分业务状态，提供可操作的错误指引。
• 双重保障：Schema 负责语义引导，服务端负责安全校验。

希望这些建议能帮助你构建更稳定、更智能的 AI 智能体。