Agent工具契约设计

它解决什么问题

Agent 团队最常见的故障不是模型能力不足，而是工具层契约不清：工具描述含糊，模型不知道何时该用、何时不该用；报错只写 error，模型拿到失败却无从恢复；几十个细碎工具撑大系统提示，模型在 search_users、get_user_by_id、list_users 之间反复选错。工具是 Agent 与外部环境之间的边界，边界模糊，上下文再大也救不回来。

技能如何工作

核心信条是 工具即契约（Tools are contracts）：给定 X 输入，返回 Y 输出，失败时给 Z 信号。工作流围绕这一原则展开：

• 合并原则（Consolidation）：语义相近、常被连续调用的操作合并为一个带参数的工具，用参数区分模式，而不是堆出 N 个工具。
• 三段式描述：每个工具描述必须回答做什么（What）、何时用（When）、返回什么（Returns），避免「处理」「管理」这类模糊动词。
• 可执行错误：错误要指明原因与下一步恢复动作（换参数、换源、重试），而不是一句「失败」。
• 命名与 MCP 接入：命名用 动词-名词（如 search_web），MCP 工具用 ServerName:tool_name 形式（如 github:create_issue）避免跨服务重名。
• 大输出策略：产生大结果时只回传摘要 + 文件路径，细节交给 filesystem-context 落盘检索。
• 工具审计：用 references/template.md 中的审计清单逐条核对。

产出是结构化工件 ToolSpec：包含命名、MCP 归属、三段式描述、参数表、可执行错误、合并关系，可直接交给下游技能消费，并附命名/描述/错误三方面最该改的点。

适用边界

• 不负责文件级溢出存储策略，交给 filesystem-context
• 不涉及多代理拓扑，交给 multi-agent-patterns
• 不做纯提示词层面的上下文压缩，交给 context-optimization

适合在新增/重构工具、设计 MCP 服务端工具、或排查「模型用错工具」问题时使用。