很多人搭 Agent 的时候有个错觉：模型选得好，Agent 就好用。结果跑起来发现——Agent 老是选错工具、参数填得莫名其妙、工具报错了它一脸茫然地重复调三次。问题往往不在模型，在工具本身没设计好。
把工具交给 Agent，和把 API 文档交给新人程序员，是两码事。人看得懂「user_id」是什么意思，能翻代码找上下文；模型只能靠你写的那段描述和参数说明来猜。所以给 Agent 写工具，本质是「写给人看不懂、但给模型看得懂的说明书」。
本文把工具设计拆成五件事：描述、参数、返回、错误、幂等，最后补上数量控制和权限收口——照着这份清单过一遍，Agent 的工具调用成功率通常会有肉眼可见的提升。
先搞清一件事：工具设计决定了 Agent 一半的能力上限
Agent 的工作循环是「想 → 选工具 → 填参数 → 拿结果 → 继续想」。这个循环里，模型能发挥的空间只有「想」和「选」，剩下的全是你的工具在决定。工具描述含糊，模型就选错工具；参数结构混乱，模型就填错字段；返回格式不统一，模型就理解不了结果；错误信息没用，模型就不知道下一步该怎么办。
工具调用这件事的底层机制，站里 Function Calling 是什么 已经讲透了。这篇讲的是它的上游——工具本身怎么写。
第一步：工具描述——模型选不选你，全看这一段
工具描述是模型唯一的判断依据。写得好不好，直接决定它会不会被选中。三个要点：说清「什么时候用」而不是「它是什么」——「查询订单状态」是描述功能，「当用户询问订单发货、物流、签收情况时使用」才是描述场景，后者让模型知道该在什么情况下调用；把边界写进去——哪些情况不该用这个工具，比如「只支持查询近 90 天订单，更早的请用历史订单工具」；动词开头、一句话讲清——别写成一段小作文，模型抓不住重点。
还有个常被忽略的细节：工具之间要有清晰的区分度。如果你同时给了「查订单」和「查物流」两个工具，描述里必须写清什么情况用哪个，否则模型会在两个之间反复横跳。工具命名也一样，get_order 和 query_order 这种近义命名，就是给模型挖坑。
第二步：参数结构——让模型少填错
参数设计的目标只有一个：把模型填错的空间压到最小。做法上：用枚举代替自由文本——状态字段别让它自由发挥，直接给 ["pending","shipped","delivered"] 这样的枚举，模型选错的概率立刻下降；必填和选填分开标——必填参数没给就报错，选填参数给默认值，别让模型猜；参数名要自解释——start_date 比 sd 好一万倍；格式写进描述——日期是 YYYY-MM-DD 还是时间戳，金额单位是元还是分，这些不写清，模型只能瞎猜。
参数嵌套层数也要控制。三层以上的嵌套对象，模型出错率会明显上升——能拍平就拍平，能用多个工具解决就别塞进一个复杂参数里。这套「约束模型输出形状」的思路，和站里 AI Agent 结构化输出 讲的是同一件事，只是对象从「最终答案」换成了「工具参数」。
第三步：返回格式——统一、简洁、可继续处理
工具返回什么，直接决定 Agent 下一步能不能想明白。三条原则：格式统一——所有工具成功时都返回 {ok: true, data: ...}，失败时都返回 {ok: false, error: ...}，模型不用为每个工具学一套解析规则；只给必要信息——返回一大坨原始 JSON 会把上下文窗口塞满，把无关字段砍掉，只留模型判断需要的那几个；金额、时间这类关键字段要做标注——单位、时区、货币写清楚，别让模型自己去猜。
上下文是稀缺资源，工具返回的每一字节都在挤占模型的思考空间。站里 AI Agent 上下文管理 里讲过「关键信息被冲掉」的问题，工具返回啰嗦就是最主要的元凶之一。
第四步：错误信息——让 Agent 能自己救回来
这是最多人做错的地方。工具报错时返回一句 Error: 500，模型除了重试什么也做不了；返回 参数 start_date 格式错误，应为 YYYY-MM-DD，你传的是 2026/9/10，模型下一轮就能自己改对。
好错误信息要包含三样东西：错在哪（哪个参数、什么原因）、怎么改（正确格式或取值范围）、能不能重试（是暂时性故障还是确定性错误）。确定性错误（参数格式错）别让模型重试，它重试一百次还是错；暂时性错误（网络超时、限流）才提示可重试，并建议退避。这套排查与重试的完整逻辑，站里 AI Agent 工具调用失败怎么排查 有清单，写工具时对照着设计错误返回即可。
第五步：幂等——重试不能变成重复扣款
Agent 会重试，这是它的本能。所以任何有副作用的工具（下单、转账、发消息、改数据）都必须是幂等的：同样的请求调两次，结果和调一次一样。做法是让调用方带一个唯一的请求 ID，服务端记住这个 ID，重复请求直接返回上次的结果而不是再执行一遍。
这条不是可选项。你想想：Agent 调用「创建订单」超时了，它不知道订单到底建没建，于是重试——如果没有幂等保护，用户就多了一单。涉及钱和对外动作的工具，幂等是底线。而这类有副作用的工具，本身就属于高风险动作，权限要单独收口，具体做法见 AI Agent 权限管理。
第六步：工具数量与权限——别一次给 50 个工具
工具不是越多越好。工具数量超过 20-30 个，模型的选择准确率会开始下降，上下文也被工具定义占满。做法：按场景分组，客服场景就只挂客服相关的工具，别把运维工具也一起塞进来；按需加载，需要时再动态挂载工具组；危险的写操作和安全的读操作分开，让模型默认只用读工具，写工具必须过审批。
工具其实就是权限的边界——给 Agent 一个工具，等于给它一类操作能力。所以工具清单本身就该是一份权限清单，谁能调、调到什么程度、要不要人工确认，都得在设计工具时就想清楚。给 Agent 挂 MCP 工具的具体接入方式，站里 OpenClaw 怎么接 MCP 工具 有完整流程，但接之前先按上面这几条把工具本身设计好，比接得多更重要。
工具上线后的验收：别只看「跑通了」
工具写完跑通一次不算数。上线前过一遍：选对率——给模型一批典型请求，看它选工具的正确率；参数正确率——统计模型填错的参数集中在哪几个字段，往往是描述不清；错误自愈率——工具报错后模型能自己改对的比例；幂等验证——手动重复调用有副作用的工具，确认不会重复执行。这四个指标就是工具质量的验收标准，和站里 AI Agent 质量门禁 的思路一致：出口要有闸，数据要能说话。
常见坑清单与适合人群
六个高频坑：描述写功能不写场景、参数用自由文本不用枚举、返回格式每个工具一套、错误信息只有错误码、有副作用的工具没做幂等、一次挂几十个工具。踩中任意一个，Agent 的表现都会明显打折。
这份清单适合：正在给 Agent 写工具、接 MCP 服务、或者自建 Function Calling 接口的开发者；也适合发现「Agent 老是调错工具」但找不到原因的人——大概率问题就出在工具描述和参数设计上。不适合的：如果你的 Agent 只是调用一两个简单只读接口，那按基本规范写清楚就够了，不必过度设计。
总结
AI Agent 工具设计，一句话流程：描述写场景 → 参数用枚举 → 返回统一格式 → 错误带修改建议 → 副作用必幂等 → 数量按场景控制。核心心法就一条：站在模型的角度想问题——它没有常识、看不到上下文、只能靠你写的字做判断。你把工具写得越「模型友好」，Agent 就越少犯低级错误。工具是 Agent 的手，手好使，脑子才能干正事。
