Agent 工具设计是把外部能力组织成便于模型理解、正确选择、安全调用并可靠验证的接口。它关注的不是底层 API 是否能够工作，而是 Agent 是否能在有限上下文中判断何时调用、怎样传参、如何理解结果，以及失败后应该采取什么行动。
一次工具调用如何由模型请求并由 Harness 执行，见 Agent 工具调用。本词条重点讨论工具本身的工程设计。
从 API 封装到 Agent 接口
直接把每个 API 端点包装成一个工具，通常会产生大量粒度过细、功能重叠的接口。面向 Agent 的工具应围绕可理解的任务目标组织，在工具数量、单个工具复杂度和中间结果开销之间取得平衡。
工具粒度没有统一答案。高频、边界清楚、参数复杂或需要独立授权的操作适合专用工具；一组输入输出相似、经常连续使用的操作可以合并；能够安全执行代码或命令的场景，也可以用通用执行器覆盖更多长尾需求。
能力的表达形式
Agent 能力常见有三种表达形式：
- 专用工具：使用稳定名称和结构化 Schema，适合精细授权、复杂参数、严格审计和高频操作；
- 通用执行器：通过 Shell、代码解释器等少量工具组合能力，灵活但需要沙盒、资源限制和更严格的风险控制；
- Agent Skills：用说明文档、脚本和参考资料描述流程，易于维护并可按需加载，但复杂参数和环境差异更容易造成执行错误。
选择时应分别评估安全与权限、参数复杂度、变更频率和模型能力。能力采用什么形态，与一次向模型暴露多少能力是两个不同问题；后者属于 Agent 工具发现。
名称、描述和参数
高质量工具定义应让模型知道“何时使用”和“何时不要使用”，而不只罗列功能。
- 名称稳定并表达动作与对象，必要时使用服务或领域前缀消除冲突；
- 描述写清适用场景、能力边界、成本和副作用；
- 参数名称具体，说明格式、单位、枚举、默认值并提供真实示例；
- 使用 Schema 校验必填字段、类型和联合约束，但不能只依赖模型遵守说明；
- 返回值说明成功状态、结构化数据、来源、时间、分页和继续读取方式；
- 错误包含稳定代码、可否重试和必要的修正提示。
功能重叠或边界模糊会使模型难以选对工具。发现误选时，应先检查名称、描述、示例和返回结构，再判断是否需要更换模型。
输入与输出保真
工具实际处理的输入必须与模型提交的参数一致。静默替换字符、补充参数或改变路径，会让模型观察到的世界与工具操作的世界产生偏差。确需规范化时，应在工具说明中公开规则，并在结果中返回规范化后的值。
输出也不能静默截断。搜索工具应返回候选摘要和分页信息；读取工具应说明已展示范围、总量和继续读取方法；超长执行日志可以保存到文件，只把高信号摘要和定位信息放入上下文。
不同工具类型的设计重点
- 感知工具获取信息，应控制返回量、保留来源并明确空结果、失败与截断的区别；只读操作通常适合缓存和并行；
- 执行工具改变外部状态，应区分可逆与不可逆操作，处理权限、确认、幂等、超时和副作用不确定性；
- 协作工具驱动其他 Agent 或人类，应提供创建、消息、取消、状态和结果归属等生命周期信息；
- 事件触发与用户沟通工具涉及异步运行和跨渠道交互，需要额外处理唤醒、去重、送达和用户控制。
安全、验证与可观测性
工具端必须重新校验身份、权限和资源范围，不能把模型输出直接当作可信命令。高风险操作应先展示目标、参数和影响范围，由用户明确确认。写操作应尽量支持幂等键、查重、预览、回滚或补偿。
如果结果可以自动验证，就应在调用后获取独立证据，例如写文件后重新读取、修改代码后运行静态检查、提交业务数据后查询最终状态。日志应记录调用关系、耗时、结果和审批，但避免保存 Token、Cookie 等凭据。
评测
工具设计应通过固定任务集和真实轨迹评测，而不是只检查单次函数是否成功。常见指标包括工具选择正确率、参数有效率、任务完成率、调用次数、延迟、Token 消耗、错误恢复率和高风险误操作数。评测结果应能定位问题来自描述、Schema、实现、权限还是模型决策。