Agent 工具接口怎样设计：参数、结果和错误都要说清楚

把 process_order 拆成读取订单、创建工单草稿和提交工单等明确能力。工具名说明动作与对象，描述写清什么时候用、什么时候不能用，以及是否改变业务状态。工具数量也不宜无限增加，重叠能力会让选择更难。

Anthropic 的工具设计文章强调明确命名、参数和高信号结果，并建议用实际任务评估工具。本文的订单合同和错误分类是本站教学设计，不是某个厂商 API。

字段名不必照抄示例。关键是业务含义能唯一解释，缺失和无效值有明确处理。默认值要安全，不能把缺失金额补成零再执行，也不能把缺失地区补成当前操作者所在地。

查询结果包含必要业务字段、来源版本、读取时点和明确状态。创建请求返回对象标识、受理或执行状态，以及下一步查询方式。结果未知就返回未知，不用 OK 让模型自行判断。

长列表提供分页、过滤和摘要模式，让调用方可以获取需要的部分。不要一次返回全部客户资料或大段内部记录。简洁输出仍要保留影响判断的条件，不能为了节省 token 去掉币种、版本或失败原因。

展示名可以帮助模型理解，稳定标识用于准确执行。模型不需要记忆无关内部细节，但不能只拿展示名修改记录。人可理解与机器可校验应同时具备。

错误不能携带 token、完整堆栈或无权资料。可操作不等于向任何用户公开内部信息；详细诊断放在受控记录中，工具返回保留决策所需信息。

检查身份、业务对象范围、当前状态、记录版本、金额或数量约束以及副作用授权。模型提出的参数只是候选，不能跳过这些检查。

schema 可以确认字段类型和枚举，不能确认这笔金额是可退余额，也不能确认当前用户拥有审批权限。模型输出“approved: true”不能成为授权记录，授权状态来自受控服务。

读工具也需要校验。一个通用搜索工具如果能跨租户返回内部资料，后续写工具再严格仍然存在数据暴露风险。工具合同应说明读结果的范围和来源。

修改工具后同步更新示例与版本。旧参数继续兼容时写清期限，未知字段和状态按约定处理，避免模型缓存的旧用法悄悄影响新流程。

保留几组相同意图、不同表达的任务，检查工具描述是否只对示例措辞有效。也要给错误结果做测试：返回“已受理但未完成”时，模型不应宣布完成；返回版本冲突时，不应换一个对象编号重试。工具评测由此覆盖调用后的解释，而不只验证参数能通过 schema。

选一个最常误用的工具，重写用途、参数含义、状态和错误。让团队里没写过它的人读文档并完成一项演练；人仍无法判断时，继续减少含糊约定。

本文适合接入业务 API 的 Agent，不要求特定框架。工具设计能够降低误用，但不能保证模型每次选择正确；执行层仍需限制范围，并对失败提供可查询与恢复的路径。