工具调用设计：如何为 Agent 定义好用的工具集

工具是 Agent 的手脚，说明书是给模型看的

Agent 调用工具靠的是工具的名称、描述和参数定义——模型读这些文本来决定何时用、怎么用。所以工具设计本质上是在写一份“给模型看的 API 文档”。文档写得含糊，模型就会用错或不用。

{
  "name": "search_orders",
  "description": "按用户条件查询订单。支持按状态、时间范围筛选。注意：一次最多返回 20 条，需要更多请用 cursor 分页。",
  "parameters": {
    "status": "订单状态：paid|shipped|completed|refunded",
    "start_date": "起始日期，格式 YYYY-MM-DD"
  }
}

这段 JSON 就是模型的全部认知来源。描述里那句“最多返回 20 条”，能避免模型以为一次拿全了数据就下结论。

工具粒度：粗与细的权衡

粒度	优势	代价
粗（一个工具干完整件事）	出错环节少，结果可控	灵活性差，组合场景覆盖不全
细（原子操作自由组合）	灵活，可应对开放任务	模型要自己编排，步骤多易出错

经验法则：面向明确任务的工具做粗，面向开放探索的工具做细。“查物流”做成一个粗工具没问题；“分析这份财报”则需要读文件、算数据、画图表等细粒度工具让模型自由组合。

产品决策提示：粒度设计的检验方法是“走一遍模型视角”——只读工具名和描述，假装自己是模型，面对一个真实任务能否想清楚该怎么一步步调用。走不通的地方就是定义的缺陷，这个练习产品经理完全能做，不需要写代码。

描述编写的五条规范

1. 说清“何时用”和“何时不用”：“查询订单状态时使用；查物流轨迹请用 get_logistics”。工具之间的边界要写明，否则模型会混用。
2. 写明限制与副作用：返回上限、耗时、是否产生实际操作（发消息、扣款），让模型在规划时有所顾忌。
3. 参数枚举值列出并解释：paid|shipped|completed 比“订单状态字符串”好得多。
4. 避免行话和内部代号：模型不了解你公司的内部术语，“查 CRM 的 P50 记录”这类描述会直接导致误用。
5. 用模型能联想到的自然语言命名：search_orders 优于 q_ord。

参数设计的坑

• 能少则少：参数越多，模型填错的概率越高。可推断的参数（如当前用户 ID）由系统注入，不要让模型传。
• 日期时间统一格式并写明时区：日期格式错误是工具调用失败的第一大原因。
• 必填与选填明确标注，给默认值。
• 返回信息要“够模型用”：返回 {"error": "date format invalid, expect YYYY-MM-DD"} 比返回 {"code": 4002} 好——模型读到前者能自我纠正重试，后者只会失败或瞎猜。

工具数量与选择

工具不是越多越好。工具列表会占用上下文，且选项越多，模型选错越多。控制手段：

• 分层路由：先让模型选“领域”（订单类、内容类、数据类），再展示该领域的具体工具——类似人类先找部门再找人。
• 按场景动态注入：对话上下文表明用户在问物流，就只挂物流相关工具。
• 定期审计使用率：上线后统计每个工具的调用频次与失败率，零调用的工具移出，高频失败的修描述或参数。

产品决策提示：把工具当 SKU 一样运营。上线只是开始，“调用成功率”“误用率”“零使用工具数”应进入 Agent 产品的常规看板，工具集需要季度级别的修剪。

一个完整例子：日程助手

设计“帮用户安排会议”的工具集：

• check_calendar（查空闲时段）——只读，安全，鼓励先用；
• create_event（创建日程）——写操作，描述注明“会实际创建日程并通知参与者”；
• send_invite（发邀请）——外部可见副作用，描述强调“发送前须与用户确认时间与参与人”。

注意 create_event 和 send_invite 分开的理由：合并成一个工具，模型就没法“先建草稿再确认”了。把确认点切分出来，是工具粒度服务于安全设计的典型手法。

本节要点

• 工具定义是给模型看的 API 文档，名称、描述、参数是模型的全部认知来源，质量直接决定调用成功率。
• 粒度权衡：明确任务做粗工具，开放探索给细工具；把安全确认点切分成独立工具是粒度设计的常用手法。
• 描述要写清何时用/何时不用、限制与副作用，参数能少则少、格式与时区写明，错误信息要让模型能自我纠正。
• 控制工具数量：分层路由、按上下文动态注入，并像 SKU 一样用调用率数据持续修剪工具集。