Tool Use：从建议走向行动
工具把模型输出连接到文件、终端、浏览器、数据库与业务系统，也把真实风险带进产品。
- 能写生产级 Tool Contract
- 能设计幂等、超时与结构化错误
- 能按动作拆分工具与权限
工具越多，Agent 就一定越强吗？
模型生成一个工具名称和参数，只是提出动作请求。Harness 还要检查参数、权限和策略，再由工具 Runtime 执行。结果必须以模型能继续判断、用户能审计的方式返回。
生产工具不能只描述成功路径。写入动作可能响应超时但实际已完成，如果系统直接重试，就会创建两份业务对象。工具合同因此还要规定幂等、回执、超时、错误类型和审计字段。
先记住这句话工具是一份带名称、说明和参数约束的能力合同。模型负责选择与填参，Harness 负责校验、授权、执行、超时、重试和返回结构化结果。
工具描述同时服务模型和策略
名称和描述帮助模型从相邻能力中选对工具，Schema 限制参数结构；权限等级和副作用说明帮助策略决定允许、审批或拒绝。万能工具看似简单，通常会让选择、授权和审计都变得模糊。
拆分不应追求越细越好，而应围绕业务语义、可逆性和权限边界。例如搜索资料、读取全文、写入草稿和正式发布应是不同能力。
错误必须告诉 Agent 下一步能做什么
暂态错误可能有限重试，永久错误需要换路径，权限错误要请求授权，输入错误要修正参数，业务冲突要交给用户判断。统一返回“未知错误”只会诱发盲目重试。
有副作用的工具应使用幂等键，并在超时后先查询回执。最终成功要包含真实对象 ID、状态和可验证时间，而不是只有一段自然语言。
工具是一份模型与真实世界之间的能力合同。名称、描述和 Schema 帮助模型选择；权限、幂等、超时、回执和错误结构保证动作能够在生产环境被信任。
从工具目录选择能力并生成结构化参数
做 Schema 校验、策略检查与必要审批
使用幂等键执行并返回结构化回执
标准化成功、暂态错误与永久错误
有术语没听懂？在这里用人话再看一遍5 个词＋
- Tool Contract
- 工具名称、描述、参数、权限、执行语义、回执、错误与审计的完整约定。
- Schema
- 对结构化参数字段、类型、必填项和允许值的约束。
- 幂等
- 同一请求重复执行不会产生重复业务结果。
- 回执
- 外部系统对动作是否发生、作用对象和当前状态的可查询证明。
- 暂态错误
- 网络抖动等可能在条件变化后恢复的错误；与稳定的权限或业务错误不同。
创建促销活动草稿，而不是误发正式活动
Agent 先查询商品和库存，再调用 create_campaign_draft；正式发布由独立高风险工具完成。
- 01
读取工具与写入工具分开授权
- 02
创建请求携带 idempotency_key
- 03
响应超时时先查询回执，不直接重试创建
即使网络抖动，也不会产生重复活动；用户能清楚区分草稿与发布。
本章依据与证据边界3 条结论 · 6 份原始材料＋
正文已经把关键来源放在相关概念旁边。这里保留完整核验清单：每条材料能支持什么、不能支持什么；不要求离开本站才能继续学习。
- [1]
Anthropic 的 Agent 工程文章强调工具定义、接口设计与环境反馈对 Agent 表现的重要性。
官方事实ANBuilding effective agents官方工程文章 · 核验 2026-07-14 - [2]
MCP 官方架构将 Tools 作为 Server 可向 Host 暴露的能力类型之一。
官方事实MOMCP architecture overview官方文档 · 核验 2026-07-14 - [3]
本站的五类错误、幂等和工具拆分规则是面向生产产品的综合设计框架。
本站推演ANBuilding effective agents官方工程文章 · 核验 2026-07-14
查看全部一手材料与源码证据 6 条
这份材料把工具定义为确定性系统与非确定性 Agent 之间的合同，说明工具名称、参数、描述、错误反馈和返回内容都会改变模型行为。它支持用真实任务和留出集评测工具，并强调更少重叠、边界清晰、返回高信号且 Token 高效的工具通常更可靠。
官方产品实现 · 核验 2026-07-11Connect Claude Code to tools via MCPAnthropic这份文档说明 Claude Code 如何通过 MCP 连接外部工具、资源、提示与事件渠道，以及 local、project、user 等配置作用域。它支持讲清 MCP 是外部能力连接协议而不是 Agent 的推理核心或长期记忆，并覆盖认证、连接、超时和共享边界。
官方方法 · 核验 2026-07-11A practical guide to building agentsOpenAI这份指南面向产品与工程团队，给出 Agent 使用场景判断、Model/Tools/Instructions 基础结构、单 Agent 与多 Agent 编排和 Guardrail 设计。它支持从复杂决策、难维护规则和非结构化信息出发选择场景，并强调先强化单 Agent、从小范围真实用户验证开始。
固定提交源码 · 核验 2026-07-11Hermes Agent repository and architecture guidanceNous Research这份固定提交的仓库说明展示 Hermes Agent 如何用同一个窄腰核心服务 CLI、TUI、桌面与消息入口，并优先通过 Skills、Plugins 与 MCP 扩展。它还把 Prompt Cache、核心工具数量和扩展 Footprint 当成真实架构约束，说明工具越多并不自动更强。
固定提交源码 · 核验 2026-07-11Hermes Agent context compression and tool runtimeNous Research这份同提交文档解释 Hermes 如何区分稳定、上下文和易变 Prompt 层，并在压力下裁剪旧工具输出、保留边界、生成结构化摘要和修复工具调用配对。它支持课程讨论上下文压缩与缓存边界，不用来证明未在该文档中展开的工具运行时。
官方方法 · 核验 2026-07-14Harnessing Claude’s intelligenceClaude by Anthropic这份官方设计说明展示 Claude Code 团队如何把模型能力放进工具、上下文、权限与反馈环境，并把 Harness 视为随模型变化而持续调整的产品系统。
证据边界：它解释团队经验，不代表每个领域都应复制 Claude Code 的产品结构。