跳到主要内容

工具设计原则

工具的粒度怎么定、描述与返回怎么设计才防呆，以及用结构约束替代 prompt 叮嘱

核心要点：

  • 工具按模型思考单元划分，不照搬 API
  • 描述即 prompt，加示例可把准确率从 72% 提到 90%
  • 返回值要 token 高效：语义名、截断、详略可选
  • 错误信息要可操作、区分可重试与终止
  • poka-yoke：用结构约束让错误调用不可能发生

本文讲单个工具怎么设计。工具协议(MCP)见 03-MCP-协议，工具数量膨胀见 04-工具发现与延迟加载。

工具该切多细？​

核心问题：一个工具对应一个 API 端点，还是对应一件"事"?

按模型的自然思考单元划分，而非机械对应 API[1]。紧密关联的操作可以聚合成一个工具，让模型少在相似工具间犹豫。

  • 聚合关联操作：用一个 schedule_event 代替"查空闲—建事件—发邀请"三个工具。
  • 用枚举参数收敛变体：用 action 枚举区分同类操作的变体，减少工具总数。
  • 集合最小且不重叠：功能重叠的工具让模型在选择上浪费推理、易出错——人类工程师都分不清该用哪个时，模型也分不清。

可借鉴的判据：工具边界应匹配"模型会怎么想这件事"，不是"后端怎么拆 API"。

工具描述要写什么？​

核心问题：工具的 description 字段，模型真会读吗？

会——Anthropic 把工具定义视为与 system prompt 同等的工程对象，描述质量直接决定调用准确率[1]。实测数据：在工具描述里加入调用示例后，准确率从 72% 升到 90%[2]。

描述要写清四件事：何时用、何时不用、参数格式要求、边界情况。命名也是描述的一部分——用 domain_verb_noun 式命名空间(如 github_list_prs)，参数名用精确名词(user_id 而非 user)。这呼应了 02-上下文工程/03-系统提示词工程:工具的接口设计(ACI)之于 agent，等同人机界面(HCI)之于人。

返回值怎么设计？​

核心问题：工具返回什么、返回多少，对 agent 有多大影响？

返回值要 token 高效，只给模型下一步需要的信息[1]。工具返回会直接进入上下文，冗余返回既费 token 又干扰推理。

  • 语义标识替代 UUID：用可读名称替代不透明 ID,Anthropic 实测可降低幻觉。
  • 详略可选：提供 response_format: concise/detailed 让模型按上下文预算选。
  • 自然格式 + 截断附恢复提示：用训练中常见的 JSON/Markdown 格式降低解析错误，截断时附带"如何取更多"的提示。

这条与 02-上下文工程/02-核心原则 的"工具返回值也是上下文成本"一致。

错误怎么反馈？​

核心问题：工具失败时，返回一个 stack trace 够吗？

不够——错误信息要是可操作的诊断，让模型能自我纠正[1]。好的错误返回包含：失败原因 + 具体纠正建议，并区分可重试错误与终止性错误。

更进一步，可以在工具描述里预先告知模型"遇到这类错误后该怎么办"。把错误当成给模型的指令，而非单纯的故障报告——这决定了 agent 能否从失败中恢复，而不是卡死或瞎试。

poka-yoke 防呆是什么？​

核心问题：与其在 prompt 里反复叮嘱模型别犯错，有没有更可靠的办法？

poka-yoke（防呆）指用结构性约束让错误调用在接口层就不可能发生，而非靠提示叮嘱[3]。这是工具设计里最可借鉴的思路——把约束硬编进接口，而不是寄望模型记住。

常见模式：强制绝对路径（消除相对路径歧义）、唯一性约束（用"替换"工具而非"新建+删除"）、读前写门控、枚举替代自由文本、输出截断边界、内嵌调用示例。核心哲学是让接口本身拒绝错误的用法，比任何 prompt 警告都可靠。

Takeaway​

知识点核心结论
粒度按模型思考单元切，聚合关联操作，集合最小不重叠
描述即 prompt写清何时用/参数/边界，加示例准确率 72%→90%
返回值token 高效：语义名替 UUID、详略可选、截断附恢复提示
错误反馈可操作诊断 + 区分可重试/终止，当作给模型的指令
poka-yoke用接口结构约束让错误调用不可能，而非 prompt 叮嘱

参考资料​

  1. Anthropic. Writing effective tools for agents — with agents. 2025. https://www.anthropic.com/engineering/writing-tools-for-agents
  2. Anthropic. Introducing advanced tool use on the Claude Developer Platform. 2026. https://www.anthropic.com/engineering/advanced-tool-use
  3. Anthropic. Building effective agents. 2024. https://www.anthropic.com/engineering/building-effective-agents

延伸阅读​