Agent 工具设计实战：工具怎么定，Agent 才好用

Agent 的能力边界 = 工具的能力边界。模型本身再聪明，工具设计得烂，Agent 照样跑不起来。这篇文章讲讲我设计工具的经验，都是被坑出来的。

工具数量的把控。

给 Agent 挂工具，不是越多越好。我一开始挂了 15 个工具，模型经常选错。后来精简到 6 个核心工具，准确率反而上来了。原因很简单：工具越多，模型做工具选择的困惑越大。

经验法则：

• 核心场景 5-8 个工具最舒服
• 超过 10 个，考虑分层：先一个"路由工具"决定走哪组，再进子工具集
• 相似功能的工具合并，别搞 search_user 和 search_user_by_name 两个

工具命名要"动词+对象"。

get_user_info 比 user 好，search_orders_by_date 比 orders 好。命名要能让模型一眼看懂"这个工具能干什么"。我见过有人用拼音缩写命名工具，模型直接懵。

参数设计。

• 参数名用全称：user_id 而不是 uid
• description 里写清楚参数格式和约束："日期格式 YYYY-MM-DD"
• 必填参数放前面
• 可选参数给默认值

工具 description 是给模型看的说明书。

这是最容易被忽视的。description 写得好不好，直接影响模型调用准确率。好的 description 包含：

• 这个工具干什么
• 什么场景用
• 返回什么
• 边界和限制

错误处理：工具要会"说人话"。

工具出错时返回的错误信息，模型会读。别返回 "Error 500"，要返回 "查询失败：城市不存在，请检查城市名"。这样模型才知道怎么纠正（换个城市名重试），而不是瞎猜。

幂等和副作用。

会改数据的工具（写库、发消息）要有明确说明，最好设计成可撤销或需确认。Agent 自动执行危险操作前，加一层人工确认（Human-in-the-loop）。

坑：

1. 工具超时。工具执行慢会让整个 Agent 卡住。每个工具设置超时，超时返回"执行超时"让模型决定重试还是放弃。

2. 工具返回太大。查询返回几千行，模型 context 爆了。工具侧先做截断和聚合。

3. 工具幻觉。模型可能调用不存在的工具名，或传错误的参数。容错解析 + 参数校验必不可少（function calling 那篇讲过）。

总结：工具设计的核心是"让模型少猜"。命名清晰、description 详细、错误可读，Agent 的稳定性立刻上一个台阶。