tool-design

面向 Agent 的工具设计

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

本技能的工作单元是单个工具或工具目录。项目形态、流水线架构、任务与模型的匹配度，以及项目层面的成本决策，属于 project-development。是否引入子 Agent，则属于 multi-agent-patterns。本技能负责连接确定性代码与 Agent 的接口层。

何时启用

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

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

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

• 决定项目是否应使用大模型，或流水线应包含哪些阶段：project-development。
• 决定是否将工作拆分给多个子 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 的上下文和注意力有限。工具集中的每个工具在工具选择时都会争夺注意力，每条描述都会消耗上下文预算令牌，而功能重叠会造成歧义。整合可以消除重复描述、消除选择歧义，并缩小有效工具集。Vercel 的 d0 案例研究提供了一个具体示例：将专业工具缩减为更小的基础工具集，并获得了更好的实测结果（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. Token 影响：大型响应支持简洁模式或文件引用模式。

示例

示例 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. 实现响应格式选项，以提高 Token 使用效率
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 就无法自行纠正。每条错误响应都应包含无效值、预期格式和具体示例。

集成

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

• project-development：项目的结构、流水线阶段的选择、任务与模型的匹配，以及项目层面的成本估算。如果问题是“正确的流水线架构是什么”，而不是“正确的工具 API 是什么”，请转到该技能。
• multi-agent-patterns：决定使用一个拥有更多工具的 Agent，还是两个工具目录较小的 Agent。如果问题是“是否应将其拆分为子 Agent”，请转到该技能。
• context-optimization：轨迹级别的令牌效率、观察内容屏蔽，以及在多次工具调用中选择响应格式选项。如果问题是“如何降低累积工具输出的令牌占用”，请转到该技能。
• context-fundamentals：工具定义如何占用注意力预算这一概念性问题。如果问题是“为什么增加工具会降低路由准确性”，请从该技能入手。
• evaluation：判断工具集是否整体改善了 Agent 的效果。

参考资料

内部参考资料：

• 最佳实践参考 - 阅读时机：从零开始设计新工具，或审查现有工具集合以发现质量方面的不足
• 架构精简案例研究 - 阅读时机：考虑用基础工具替代专用工具，或评估复杂的工具架构是否合理

本合集中的相关技能：

• context-fundamentals - 工具上下文交互
• evaluation - 工具测试模式

外部资源：

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

---

技能元数据

创建时间：2025-12-20 最后更新：2026-05-15 作者：Agent Skills for Context Engineering Contributors 版本：2.2.0