把工具定义写好

工具描述就是一句 prompt，而且是模型最依赖的那一句。含糊的描述造成的 agent 失败，比推理能力弱造成的还多。

agent 表现不对时，第一反应是怪推理能力。但通常问题出在工具定义上。

模型挑选工具，靠的是工具的名字、描述和参数 schema——除此之外没有别的。它读不到你的实现。定义就是全部接口，而它就是一句 prompt，适用于所有让 prompt 生效的规律。

干活的是描述

对比一下：

"description": "搜索数据库"

以及：

"description": "按关键词搜索客服工单。
最多返回 20 条匹配的工单，含 id、subject、status 和
创建日期。搜索工单的主题和正文，不含附件。
用于查找某个话题的工单。不要用它按 ID 查
某条具体工单——那种情况用 get_ticket。"

第二个回答了它做什么、返回什么、不覆盖什么、什么时候用它、什么时候该用别的。每一个问题的答案都防住了一类具体的错误。

一段描述应该始终覆盖四件事：

它做什么，精确到足以与邻近的工具区分开。

它返回什么，好让模型能规划下一步。

什么时候用它，尤其是相对于相似工具而言。

**它不做什么。**最常被跳过、也最有价值的一部分。划清边界对误用的防止作用，比罗列能力对正确使用的促进作用更强。

把歧义往死里消

最常见的失效是两个工具的描述有重叠。search_tickets 和 find_issues——模型无从选择。

修法按优先级排：把它们合并成一个带参数的工具；或者让描述明确形成对照，每个都点名对方，并说明什么时候更该选自己。

名字也有分量。get_user_by_email 强过 lookup——光凭名字就传达了参数和用途。

参数设计

schema 的形状影响的不只是合法性，还有可靠性。

用枚举，别用自由字符串。"status": {"enum": ["open","closed","pending"]} 不可能产出非法的状态值。而自由文本的状态字段经常就会。

**用扁平结构，别用嵌套。**嵌套很深的参数更容易出错。能拍平就拍平。

每个参数都要写描述，包括那些看起来很明显的。尤其是格式："date": {"type": "string", "description": "ISO 8601, e.g. 2026-03-15"}。不给例子，就要做好收到世上所有日期格式的准备。

**准确标注必填字段。**标着可选、实际必填，是产生畸形调用的一条稳定来源。

**给「不确定」留一个去处。**如果模型可能不知道某个值，就提供一个 null 选项，或者一个明确的 UNKNOWN。没有这个东西，它就会编一个值出来——这和别处促成编造的是同一种交差压力。

能设默认值就别设必填。决定越少，错误越少。

把面铺得小一点

工具集变大，选工具的准确率就会下降，工具彼此相似时尤其明显。超过十几个之后，混淆就成了常态。

三种应对：

**合并。**五个各自专用的搜索工具，通常应该变成一个带参数的工具。

**路由。**只暴露与当前任务相关的工具，在模型看到它们之前就由你的代码挑好。

**分层。**先给一个返回可用子操作列表的工具，再用第二次调用去执行其中一个。多一次往返，换来顶层够小。

每个工具定义还会在每一次请求里消耗 token。二十个啰嗦的定义，就是每次调用一笔实打实的开销。

返回值同样要紧

工具返回的结果会进入上下文窗口，并在接下来的整个循环里一直待在那儿。

**只返回有用的字段。**三个字段有用却把整行数据库记录倒出来，会在之后每一次迭代里浪费预算。

把错误当成数据返回，而不是抛异常。{"error": "No ticket with that ID", "suggestion": "Use search_tickets to find it"} 能让模型自己恢复。抛出异常则直接终止这一轮。

**把能支撑下一步的信息带上。**如果结果分页了，就说清楚并返回游标。如果被截断了，也要说明——否则模型会把残缺的列表当成完整的。

**形状稳定、自描述。**模型是把这些当文本读的；带字段名的字段胜过按位置排列的数组。

直接测这些定义

工具定义可以脱离 agent 单独测试，而且值得这么做。

给模型一个任务和一套工具，在执行任何操作之前，先检查它挑了哪个工具、带了什么参数。选错就直接指向描述的问题。

有歧义的任务才是有用的测试用例。如果有两个工具看起来都可能适用，那正是描述需要形成对照的地方。

要点回顾

定义就是完整的接口，模型看不到别的。
覆盖它做什么、返回什么、什么时候用，以及它不做什么。
描述重叠是头号失效——要么合并，要么让它们明确形成对照。
枚举、扁平参数、格式示例，以及给不确定留的位置，都能提高可靠性。
工具集要小；合并、路由，或者分层。
返回精简的结果，错误以数据形式返回，好让循环能恢复。

下一篇： 多步规划

agent 表现不对时，第一反应是怪推理能力。但通常问题出在工具定义上。

干活的是描述

对比一下：

"description": "搜索数据库"

以及：

"description": "按关键词搜索客服工单。
最多返回 20 条匹配的工单，含 id、subject、status 和
创建日期。搜索工单的主题和正文，不含附件。
用于查找某个话题的工单。不要用它按 ID 查
某条具体工单——那种情况用 get_ticket。"

第二个回答了它做什么、返回什么、不覆盖什么、什么时候用它、什么时候该用别的。每一个问题的答案都防住了一类具体的错误。

一段描述应该始终覆盖四件事：

它做什么，精确到足以与邻近的工具区分开。

它返回什么，好让模型能规划下一步。

什么时候用它，尤其是相对于相似工具而言。

**它不做什么。**最常被跳过、也最有价值的一部分。划清边界对误用的防止作用，比罗列能力对正确使用的促进作用更强。

把歧义往死里消

最常见的失效是两个工具的描述有重叠。search_tickets 和 find_issues——模型无从选择。

修法按优先级排：把它们合并成一个带参数的工具；或者让描述明确形成对照，每个都点名对方，并说明什么时候更该选自己。

名字也有分量。get_user_by_email 强过 lookup——光凭名字就传达了参数和用途。

参数设计

schema 的形状影响的不只是合法性，还有可靠性。

用枚举，别用自由字符串。"status": {"enum": ["open","closed","pending"]} 不可能产出非法的状态值。而自由文本的状态字段经常就会。

**用扁平结构，别用嵌套。**嵌套很深的参数更容易出错。能拍平就拍平。

**准确标注必填字段。**标着可选、实际必填，是产生畸形调用的一条稳定来源。

能设默认值就别设必填。决定越少，错误越少。

把面铺得小一点

工具集变大，选工具的准确率就会下降，工具彼此相似时尤其明显。超过十几个之后，混淆就成了常态。

三种应对：

**合并。**五个各自专用的搜索工具，通常应该变成一个带参数的工具。

**路由。**只暴露与当前任务相关的工具，在模型看到它们之前就由你的代码挑好。

**分层。**先给一个返回可用子操作列表的工具，再用第二次调用去执行其中一个。多一次往返，换来顶层够小。

每个工具定义还会在每一次请求里消耗 token。二十个啰嗦的定义，就是每次调用一笔实打实的开销。

返回值同样要紧

工具返回的结果会进入上下文窗口，并在接下来的整个循环里一直待在那儿。

**只返回有用的字段。**三个字段有用却把整行数据库记录倒出来，会在之后每一次迭代里浪费预算。

**把能支撑下一步的信息带上。**如果结果分页了，就说清楚并返回游标。如果被截断了，也要说明——否则模型会把残缺的列表当成完整的。

**形状稳定、自描述。**模型是把这些当文本读的；带字段名的字段胜过按位置排列的数组。

直接测这些定义

工具定义可以脱离 agent 单独测试，而且值得这么做。

给模型一个任务和一套工具，在执行任何操作之前，先检查它挑了哪个工具、带了什么参数。选错就直接指向描述的问题。

有歧义的任务才是有用的测试用例。如果有两个工具看起来都可能适用，那正是描述需要形成对照的地方。

要点回顾

定义就是完整的接口，模型看不到别的。
覆盖它做什么、返回什么、什么时候用，以及它不做什么。
描述重叠是头号失效——要么合并，要么让它们明确形成对照。
枚举、扁平参数、格式示例，以及给不确定留的位置，都能提高可靠性。
工具集要小；合并、路由，或者分层。
返回精简的结果，错误以数据形式返回，好让循环能恢复。

下一篇： 多步规划