tool-design

面向 Agent 的工具设计

将每个工具设计为确定性系统与非确定性 Agent 之间的契约。与面向人类的 API 不同，面向 Agent 的工具必须仅凭描述就明确契约：Agent 会根据描述推断意图，并生成必须符合预期格式的调用。每一处歧义都可能导致故障，而再多的提示词工程也无法解决。

此技能的工作单元是单个工具或工具目录。是否引入子 Agent 属于 multi-agent-patterns 的职责。此技能负责将确定性代码与 Agent 连接起来的接口层。

何时启用

当工作单元是工具时，启用此技能：

• 编写新的工具描述、架构或响应格式。
• 调试 Agent 选错工具或生成格式错误的调用的情况。
• 整合存在重叠的工具目录（典型情况是“我们有 17 个工具，Agent 有一半时间都选错”）。
• 设计可操作的错误消息，让 Agent 能自行纠正。
• 在目录中统一工具和参数的命名方式（MCP 命名空间、动词-名词命名）。
• 在添加第三方工具前，根据整合原则评估该工具。

对于由其他技能负责的相关工作，不要启用此技能：

• 决定将工作拆分给多个子 Agent，还是让单个 Agent 使用更多工具：multi-agent-patterns。
• 在轨迹层面减少工具输出的 Token 权重（观察内容屏蔽、大规模选择格式选项）：context-optimization。

核心概念

围绕整合原则设计工具：如果人类工程师都无法明确判断在某种情况下应该使用哪个工具，就不能指望 Agent 做得更好。精简工具集，直到每个工具都只有一个明确用途，因为 Agent 会通过比较描述来选择工具，任何重叠都会导致选择错误。

将每条工具描述都视为会影响 Agent 行为的提示词工程。描述不是写给人看的文档——它会注入 Agent 的上下文，并直接引导推理。编写描述时，应说明工具的功能、适用场景和返回内容，因为 Agent 在选择工具时恰恰会评估这三个问题。

详细主题

工具与 Agent 的接口

将工具视为契约 将每个工具设计为独立完整的契约。人类调用 API 时会阅读文档、理解约定并提出合适的请求。Agent 必须仅凭一段描述推断完整契约。通过加入格式示例、预期模式和明确约束，确保契约清晰无歧义。不要遗漏调用者需要了解的任何信息，因为 Agent 在调用前无法提出澄清问题。

将工具描述视为提示词 编写工具描述时，要意识到它们会直接载入 Agent 的上下文，并共同引导其行为。像“搜索数据库”这样含糊的描述，配上晦涩的参数名称，会迫使 Agent 猜测——而猜测会导致错误调用。相反，应提供使用场景、参数格式示例和合理的默认值。描述中的每个词都可能提高或降低工具选择的准确性。

命名空间与组织 随着工具集不断扩大，应使用通用前缀为工具划分命名空间，因为分层组织有助于 Agent 进行分组。需要执行数据库操作时，Agent 会转向 db_* 命名空间；需要进行 Web 交互时，则会转向 web_*。如果没有命名空间，Agent 就必须在扁平列表中逐一评估所有工具，随着工具数量增加，选择准确性会下降。

整合原则

构建单一综合工具 构建单一综合工具，而不是多个功能狭窄且相互重叠的工具。与其分别实现 list_users、list_events 和 create_event，不如实现 schedule_event，在一次调用中查找可用时间并安排日程。综合工具在内部处理完整工作流，免去 Agent 按正确顺序串联调用的负担。

整合为何有效 应采用整合方式，因为 Agent 的上下文和注意力有限。工具集合中的每个工具在工具选择时都会争夺注意力，每条描述都会占用上下文预算，而功能重叠会造成歧义。整合可以消除冗余描述，避免选择歧义，并缩减实际工具集。《架构精简案例研究》提供了一个具体示例：将专用工具精简为更小的基础工具集，并取得了更好的实测结果（claim-tool-design-vercel-d0-reduction）。

何时不应整合 如果工具的行为有本质区别、服务于不同上下文，或必须能够独立调用，就应将它们分开。过度整合会带来另一类问题：参数和模式过多的单一工具，会让 Agent 难以正确设置参数。

架构精简

将整合原则推向极致：移除大多数专用工具，转而采用基础、通用的能力。生产环境证据表明，这种方法可能优于复杂的多工具架构。

文件系统 Agent 模式 通过单一命令执行工具提供直接文件系统访问，而不是为数据探索、模式查询和查询验证构建自定义工具。Agent 使用标准 Unix 工具（grep、cat、find、ls）来探索和操作系统。这种方法行之有效，是因为文件系统是久经验证、且模型深入理解的抽象；标准工具的行为可预测；Agent 可以灵活地串联基础工具，而不受预定义工作流限制；文件中的优质文档也可以取代摘要工具。

何时精简优于复杂化 当数据层文档完善且结构一致、模型具备足够的推理能力、专用工具是在限制而非赋能模型，或花在维护脚手架上的时间超过了改进结果的时间时，应选择精简。如果底层数据杂乱或文档不完善、领域需要模型不具备的专门知识、安全约束必须限制 Agent 的操作，或操作确实能从结构化工作流中受益，则应避免精简。

面向未来模型构建 设计能从模型进步中受益的最简架构，而非锁定当前局限的复杂架构。思考每个工具究竟是赋予新能力，还是限制模型本可自行完成的推理——作为“护栏”构建的工具，往往会随着模型进步而成为负担。

参阅架构精简案例研究，了解生产环境证据。

工具描述工程

描述结构 每个工具的描述都应回答四个问题：

1. 工具的作用是什么？准确说明工具能完成什么，不要使用“有助于”或“可用于”等含糊表述。
2. 何时应使用该工具？说明直接触发条件（“用户询问价格”）和间接信号（“需要当前市场费率”）。
3. 工具接受哪些输入？说明每个参数的类型、约束、默认值和格式示例。
4. 工具会返回什么？说明输出格式、结构、成功响应示例和错误情况。

默认参数选择 设置默认值以反映常见用例。默认值可以免去 Agent 不必要的参数指定，减轻其负担，并避免因遗漏参数而出错。选择能直接产生有用结果的默认值，无需 Agent 了解所有选项。

响应格式优化

提供响应格式选项（简洁版与详细版），因为工具响应大小会显著影响上下文用量。简洁格式仅返回必要字段，适用于确认场景。详细格式返回完整对象，适用于需要完整上下文来做决策的场景。在工具描述中说明各格式的适用时机，以便 Agent 学会恰当选择。

错误消息设计

设计错误消息时应兼顾两类受众：调试问题的开发者，以及从故障中恢复的 Agent。对于 Agent，每条错误消息都必须具有可操作性——指出出了什么问题，以及如何纠正。对于可重试错误，应提供重试指导；对于输入错误，应提供修正后的格式示例；对于请求不完整的情况，应明确指出缺少哪些字段。只说“失败”的错误消息无法提供任何恢复线索。

工具定义架构

在所有工具中采用一致的架构。工具名称使用动词-名词模式（get_customer、create_order），参数名称保持一致（始终使用 customer_id，不要有时用 id，有时用 identifier），返回字段名称也应保持一致。一致性可以降低 Agent 的认知负担，并提升跨工具泛化能力。

工具集合设计

将工具集合限制为数量最少且用途互不重叠的一组，因为描述重叠会令模型困惑，而且工具数量增加并不总能带来更好的结果。当确实需要更多工具时，使用命名空间创建逻辑分组。实现选择机制：按领域对工具分组、提供基于示例的选择提示，以及使用可路由到专用子工具的总括工具。

MCP 工具命名要求

始终使用包含 MCP（Model Context Protocol）的全限定工具名称，以避免出现“找不到工具”错误。

格式：ServerName:tool_name

# Correct: Fully qualified names
"Use the BigQuery:bigquery_schema tool to retrieve table schemas."
"Use the GitHub:create_issue tool to create issues."

# Incorrect: Unqualified names
"Use the bigquery_schema tool..."  # May fail with multiple servers

如果没有服务器前缀，当存在多个 MCP 服务时，Agent 可能无法找到工具。应建立包含服务器上下文的命名规范，并在所有工具引用中遵循。

使用 Agent 优化工具

将观察到的工具故障反馈给 Agent，以便诊断问题并改进描述。在目标工具目录中复现之前，应将报告的效率提升视为仅适用于特定工作负载。

工具测试 Agent 模式：

def optimize_tool_description(tool_spec, failure_examples):
    """
    Use an agent to analyze tool failures and improve descriptions.

    Process:
    1. Agent attempts to use tool across diverse tasks
    2. Collect failure modes and friction points
    3. Agent analyzes failures and proposes improvements
    4. Test improved descriptions against same tasks
    """
    prompt = f"""
    Analyze this tool specification and the observed failures.

    Tool: {tool_spec}

    Failures observed:
    {failure_examples}

    Identify:
    1. Why agents are failing with this tool
    2. What information is missing from the description
    3. What ambiguities cause incorrect usage

    Propose an improved tool description that addresses these issues.
    """

    return get_agent_response(prompt)

这会形成一个反馈循环：使用工具的 Agent 生成故障数据，Agent 再利用这些数据改进工具描述，从而减少未来的故障。

测试工具设计

根据五项标准评估工具设计：明确性、完整性、可恢复性、效率和一致性。通过提供有代表性的 Agent 请求进行测试，并依据预期行为评估由此产生的工具调用。

实用指南

工具选择框架

设计工具集合时：

1. 确定 Agent 必须完成的不同工作流
2. 将相关操作归入功能全面的工具
3. 确保每个工具的用途清晰明确
4. 记录错误情况和恢复路径
5. 使用实际的 Agent 交互进行测试

工具审计清单

将工具添加到 Agent 前，请逐项使用此清单审核：

1. 名称：采用动词-名词结构；如果目录包含多个领域，则使用命名空间。
2. 描述：说明工具的功能、适用场景以及返回内容。
3. 架构：每个参数都应注明类型、约束、默认值和示例值。
4. 返回结构：成功和错误载荷都有文档说明，且机器可读。
5. 恢复：每条错误信息都能告知 Agent 重试前需要修改什么。
6. 重叠：没有其他工具具有相同的触发场景。
7. 合并决策：除非需要独立调用，否则应合并相邻的窄用途工具。
8. 令牌影响：大型响应应支持简洁模式或文件引用模式。

示例

示例 1：设计良好的工具

def get_customer(customer_id: str, format: str = "concise"):
    """
    Retrieve customer information by ID.

    Use when:
    - User asks about specific customer details
    - Need customer context for decision-making
    - Verifying customer identity

    Args:
        customer_id: Format "CUST-######" (e.g., "CUST-000001")
        format: "concise" for key fields, "detailed" for complete record

    Returns:
        Customer object with requested fields

    Errors:
        NOT_FOUND: Customer ID not found
        INVALID_FORMAT: ID must match CUST-###### pattern
    """

示例 2：糟糕的工具设计

此示例展示了几种工具设计反模式：

def search(query):
    """Search the database."""
    pass

此设计的问题：

1. 名称含糊："search" 有歧义——搜索什么？出于什么目的？
2. 缺少参数：使用什么数据库？查询应采用什么格式？
3. 没有返回值说明：此函数会返回什么？列表、字符串，还是错误处理信息？
4. 没有使用场景说明：Agent 何时应使用此工具，而不是其他工具？
5. 没有错误处理：数据库不可用时会发生什么？

失败模式：

• Agent 可能在应该使用更具体的工具时调用此工具
• Agent 无法确定正确的查询格式
• Agent 无法解读结果
• Agent 无法从故障中恢复

指南

1. 编写描述时，说明工具的功能、适用场景和返回内容
2. 通过合并减少歧义
3. 实现响应格式选项，提高令牌使用效率
4. 设计便于 Agent 恢复的错误消息
5. 建立并遵循一致的命名规范
6. 限制工具数量，并使用命名空间进行组织
7. 通过实际的 Agent 交互测试工具设计
8. 根据观察到的失败模式进行迭代
9. 思考每个工具是在赋能模型，还是在限制模型
10. 优先选择原始、通用的工具，而不是专用封装
11. 将精力投入文档质量，而不是工具复杂度
12. 构建能够从模型改进中受益的最小化架构

易踩之处

1. 描述含糊：像“搜索数据库以查找客户信息”这样的描述留下了太多未解的问题。请说明具体的数据库、查询格式和返回结构。
2. 参数名称晦涩：名为 x、val 或 param1 的参数会迫使 Agent 猜测其含义。请使用能体现用途的描述性名称，无需查阅更多文档也能理解。
3. 缺少错误恢复指引：工具失败时若只返回“发生错误”之类的通用消息，就无法为 Agent 提供恢复线索。每条错误响应都必须说明出了什么问题以及接下来可以尝试什么。
4. 工具间命名不一致：一个工具使用 id，另一个使用 identifier，第三个使用 customer_id，这会造成困惑。请在整个工具集合中统一参数名称。
5. MCP 命名空间冲突：多个 MCP 工具提供方注册了名称相似的工具时（例如，两个服务都公开 search），Agent 将无法区分它们。请始终使用完全限定的 ServerName:tool_name 格式，并在添加新提供方时检查是否存在冲突。
6. 工具描述过时：随着底层 API 演进，描述会变得不准确——参数可能新增，返回格式可能改变，错误代码也可能调整。请像对待代码一样管理描述：为其设定版本，在 API 变更期间审查，并针对当前行为进行测试。
7. 过度合并：让单个工具处理过多工作流，会导致参数列表过长，使 Agent 难以选出正确的组合。如果一个工具需要超过 8-10 个参数，或用于截然不同的场景，请将其拆分。
8. 参数过多：可选参数太多会加重 Agent 的决策负担。Agent 必须评估的每个参数都会增加认知负担。请提供合理的默认值，将相关选项归入格式预设，并把很少使用的参数移入 options 对象。
9. 错误上下文缺失：错误消息若只说“失败”或“输入无效”，却不指出哪个输入有问题、失败原因或有效输入的样式，Agent 就无法自行纠正。每条错误响应都应包含无效值、预期格式和具体示例。

集成

此技能负责工具接口层。相邻领域的决策由其他部分负责：

• multi-agent-patterns：决定一个拥有更多工具的 Agent 是否优于两个工具目录更小的 Agent。如果问题是“是否应该拆分为多个子 Agent”，请转到此处。
• context-optimization：轨迹级别的令牌效率、观察结果屏蔽，以及在多次工具调用中选择响应格式选项。如果问题是“如何降低累积工具输出的令牌开销”，请转到此处。
• context-optimization（references/fundamentals.md）：关于工具定义如何占用注意力预算的概念性问题。如果问题是“为什么添加工具会降低路由准确率”，请从此处开始。
• evaluation：评估工具集是否整体改善了 Agent 的结果。

参考资料

内部参考资料：

• 最佳实践参考 - 适用于：从头开始设计新工具，或审查现有工具集合以发现质量差距
• 架构精简案例研究 - 适用于：考虑用原语替代专用工具，或评估复杂工具架构是否合理

本集合中的相关技能：

• context-optimization（基础知识参考）- 工具上下文交互
• evaluation - 工具测试模式

外部资源：

• MCP（Model Context Protocol）文档 - 适用于：为多服务 Agent 环境实现工具，或调试工具路由故障
• 框架工具约定 - 适用于：采用新的 Agent 框架，并需要将工具设计原则映射到特定框架的 API
• 面向 Agent 的 API 设计最佳实践 - 适用于：将现有的面向人类的 API 转换为面向 Agent 的工具接口
• Agent 架构案例研究 - 适用于：评估是否要整合工具，或寻找有关架构精简的生产环境证据