工具 schema 与描述设计

Agent 开发进阶考 9 题讲解 3 段

模型选不准、填不对工具，八成是 schema 与描述的问题：名字要说清「做什么」而不是「怎么实现」、参数少而正交、描述里写清什么时候不该用。七条硬规则之外，方法是先建评测再改描述，不凭感觉调。

也叫：工具设计 · 工具描述 · tool schema · 选择准确率

工具设计七条硬规则出自 T3-2

规则	反例	正例
搜索优于罗列	`list_all_contacts()` 返回全部	`search_contacts(query, limit=10)`
参数名消歧	`user`	`user_id`（明确是 id 不是姓名）
命名加前缀分组	`search`、`create`	`crm_search_contact`、`jira_create_issue`
功能合并去重叠	5 个近义的取消/退款工具	1 个 `order_action(action: enum)`
返回值默认精简	整个订单 JSON	默认 8 字段，`fields` 参数按需展开
描述写清边界	"取消订单"	"取消未发货订单；已发货请用 return_request"
错误信息可操作	`Error 400`	`参数 date 需为 YYYY-MM-DD，你传入 "上周三"`