关于 tool-design
tool-design 是一项面向 Agent 工具设计与评估的技能，涵盖工具描述、整合、响应与错误设计，并讨论何时适合简化架构。
主要功能
- 01设计 Agent 与工具的接口
- 02工具整合原则
- 03架构简化指导
- 04描述与模式规范
- 05响应和错误设计
- 06评估工具集合
适用场景
- 01为新 Agent 系统设计工具
- 02排查工具误用与故障
- 03减少工具集合中的功能重叠
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/tool-design确认已加载。
详细介绍
何时使用本技能
构建 Agent 能够有效使用的工具，包括架构简化模式
当你使用 Agent 能够有效使用的构建工具（包括架构简化模式）时，请使用本技能。
面向 Agent 的工具设计
工具是 Agent 与外部世界交互的主要机制。它们定义了确定性系统与非确定性 Agent 之间的契约。与为开发者设计的传统软件 API 不同，工具 API 必须为能够推理意图、推断参数值并根据自然语言请求生成调用的大模型而设计。糟糕的工具设计会制造出任何提示词工程都无法修复的失效模式。有效的工具设计遵循特定原则，这些原则考虑了 Agent 如何感知和使用工具。
何时使用
在以下情况下启用本技能：
- 为 Agent 系统创建新工具
- 调试与工具相关的故障或误用
- 优化现有工具集以提升 Agent 表现
- 从零开始设计工具 API
- 评估用于 Agent 集成的第三方工具
- 在代码库中统一工具约定
核心概念
工具是确定性系统与非确定性 Agent 之间的契约。合并原则指出，如果人类工程师无法明确说出在给定情况下应使用哪个工具，就不能指望 Agent 做得更好。有效的工具描述是一种提示词工程，用于塑造 Agent 的行为。
关键原则包括：清晰的描述，回答做什么、何时使用以及返回什么；在完整性与 token 效率之间取得平衡的响应格式；能够支持恢复的错误消息；以及降低认知负担的一致约定。
详细主题
工具与 Agent 的接口
工具即契约 工具是确定性系统与非确定性 Agent 之间的契约。当人类调用 API 时，他们理解契约并提出恰当的请求。Agent 则必须从描述中推断契约，并生成符合预期格式的调用。
这一根本差异要求重新思考 API 设计。契约必须无歧义，示例必须展示预期模式，错误消息必须指导纠正。工具定义中的每一处歧义都会成为潜在的失效模式。
工具描述即提示词 工具描述会被加载到 Agent 上下文中，并共同引导其行为。这些描述不只是文档——它们是塑造 Agent 如何推理工具使用的提示词工程。
像“搜索数据库”这样描述简陋、参数名晦涩的工具会迫使 Agent 去猜测。经过优化的描述会包含使用场景、示例和默认值。描述要回答：该工具做什么、何时使用它，以及它会产生什么。
命名空间与组织 随着工具集合不断增长，组织变得至关重要。命名空间将相关工具归入共同前缀之下，帮助 Agent 在合适时机选择合适的工具。
命名空间在功能之间划出清晰边界。当 Agent 需要数据库信息时，它会路由到数据库命名空间。当它需要网页搜索时，它会路由到网页命名空间。
整合原则
综合型工具 整合原则指出，如果人类工程师无法明确判断在某种情况下该使用哪个工具，就不能指望 Agent 做得更好。因此，应优先选择单一综合型工具，而不是多个用途狭窄的工具。
不要分别实现 list_users、list_events 和 create_event，而应实现 schedule_event，由它查找可用时间并安排日程。综合型工具在内部处理完整工作流，而不必要求 Agent 连续发起多个调用。
整合为何有效 Agent 的上下文和注意力有限。在工具选择阶段，工具集合中的每个工具都会争夺注意力。每个工具都会增加说明文本的 token 数量，消耗上下文预算。功能重叠会造成歧义，让人不确定该使用哪个工具。
整合通过消除重复说明来减少 token 消耗。它让一个工具覆盖每个工作流，从而消除歧义。它还通过缩小实际工具集，降低工具选择的复杂度。
不应整合的情况 整合并非在所有情况下都正确。行为本质不同的工具应保持独立。在不同上下文中使用的工具，分开设置会更好。可能独立调用的工具不应被人为捆绑。
架构精简
将整合原则推向极致，就会走向架构精简：移除大多数专用工具，改用原始的通用能力。生产环境的证据表明，这种方法可能胜过复杂的多工具架构。
文件系统 Agent 模式 在可信的隔离环境中，范围受限的文件系统／命令工具可以替代某些自定义探索工具；这种做法牺牲了架构层面的限制，换取更广泛的执行权限，必须根据威胁模型进行评估。Agent 使用标准 Unix 实用工具（grep、cat、find、ls）来探索、理解并操作你的系统。
这种方法有效，因为：
- 文件系统是一种成熟的抽象，模型对其理解深入
- 标准工具的行为可预测且文档齐全
- Agent 可以灵活组合原始操作，而不受预定义工作流的限制
- 文件中的优质文档可以替代摘要工具
精简胜过复杂的情况 以下情况适合精简：
- 你的数据层文档齐全，结构一致
- 模型具备足够的推理能力来处理复杂情况
- 你的专用工具是在限制模型，而非帮助模型
- 你花在维护脚手架上的时间多于改善成果的时间
以下情况精简会失效：
- 底层数据杂乱、不一致或文档不完善
- 该领域需要模型不具备的专门知识
- 安全约束要求限制 Agent 的操作能力
- 操作确实复杂，适合采用结构化工作流
将推理灵活性与安全边界分开 一种常见的反模式是构建工具来“保护”模型免受复杂性影响，例如预先筛选上下文、限制选项，或在交互过程中加入验证逻辑。应评估这些做法对易用性的影响，但无论模型质量如何，都应保留服务端授权、验证、沙箱、配额和数据边界。
不妨问问自己：你的工具是在提供新能力，还是在限制模型本可独立完成的推理？
面向未来模型构建 模型的进步速度快于工具的更新速度。针对当下模型优化的架构，可能会过度限制未来的模型。应构建能够从模型进步中获益的精简架构，而不是锁定当前局限的复杂架构。
请参阅《架构精简案例研究》，了解生产环境的证据。
工具描述工程
描述结构 有效的工具描述需要回答四个问题：
工具有什么作用？清晰、具体地描述功能。避免使用“有助于”或“可用于”等含糊表述。准确说明工具能完成什么。
何时应该使用？说明具体的触发条件和情境。既包括直接触发条件（“用户询问价格”），也包括间接信号（“需要当前市场费率”）。
工具接受哪些输入？说明参数的类型、限制和默认值。解释每个参数的作用。
工具会返回什么？说明输出格式和结构。提供成功响应和错误情况的示例。
对于写入、发送、付费或删除类工具，应将预览与提交分开，并将授权绑定到确切的目标和参数。在服务端强制执行租户／用户访问控制；绝不能将模型提供的 ID 等同于权限。应包含幂等键和可观察的操作 ID，以应对结果不确定的情况；设置有界重试／超时，并对错误信息进行脱敏。返回的页面／工具内容是不可信数据，不是指令或授权。
默认参数选择 默认值应体现常见用法。通过免去不必要的参数指定，减轻 Agent 的负担。它们还能避免因遗漏参数而产生错误。
响应格式优化
工具响应的大小会显著影响上下文用量。提供响应格式选项，让 Agent 能控制详细程度。
简洁格式仅返回必要字段，适合确认信息或提供基本信息。详细格式返回包含所有字段的完整对象，适合需要完整上下文来做决策的情况。
在工具描述中说明何时使用每种格式。Agent 会学习根据任务需求选择合适的格式。
错误消息设计
错误消息面向两类受众：调试问题的开发者，以及从故障中恢复的 Agent。对于 Agent，错误消息必须具有可操作性。它们必须说明出了什么问题，以及如何纠正。
设计能够帮助恢复的错误消息。对于可重试错误，应提供重试指引。对于输入错误，应提供正确的格式。对于缺失数据，应说明需要哪些内容。
工具定义架构
所有工具应采用一致的架构。建立命名约定：工具名称使用“动词－名词”模式；工具之间的参数名称保持一致；返回字段名称保持一致。
工具集合设计
研究表明，工具描述重叠会导致模型困惑。工具数量增加并不总能带来更好的结果。对于大多数应用，合理的参考范围是 10-20 个工具。如果需要更多工具，可使用命名空间建立逻辑分组。
实施有助于 Agent 选择正确工具的机制：工具分组、基于示例的选择，以及由总括工具将请求路由到专用子工具的层级结构。
MCP 工具命名要求
使用 MCP（Model Context Protocol）工具时，始终使用完全限定的工具名称，以避免出现“tool not found”错误。
客户端显示名称可以使用 ServerName:tool_name，但 MCP 本身通过该服务连接上 tools/list 返回的 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
如果没有服务前缀，Agent 可能无法找到工具，尤其是在有多个 MCP 服务可用时。建立命名约定，确保所有工具引用都包含服务上下文。
使用 Agent 优化工具
Claude 可以优化自身的工具。向它提供工具和已观察到的故障模式后，它会诊断问题并提出改进建议。应在留出任务集上衡量这种方法；此处未提供普遍适用的 40% 时间缩减的可复现证据。
工具测试 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 请求并评估生成的工具调用来测试工具。
实用指南
应避免的反模式
描述含糊：“在数据库中搜索客户信息”会留下太多未解答的问题。
参数名称晦涩：名为 x、val 或 param1 的参数会迫使 Agent 猜测其含义。
缺少错误处理：仅返回通用错误的工具无法提供恢复指导。
命名不一致：有些工具使用 id，有些使用 identifier，还有些使用 customer_id，会造成混淆。
工具选择框架
设计工具集合时：
- 确定 Agent 必须完成的不同工作流
- 将相关操作归类到功能全面的工具中
- 确保每个工具的用途清晰明确
- 记录错误情况和恢复路径
- 使用实际的 Agent 交互进行测试
示例
示例 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
此设计的问题：
- 名称含糊：“search”含义不明确——搜索什么？目的是什么？
- 缺少参数：使用哪个数据库？query 应采用什么格式？
- 没有返回值说明：此函数返回什么？列表、字符串，还是错误处理信息？
- 没有使用场景说明：Agent 何时应使用此工具，而不是其他工具？
- 没有错误处理：如果数据库不可用，会发生什么？
失败模式：
- Agent 可能会在应该使用更具体工具时调用此工具
- Agent 无法确定正确的 query 格式
- Agent 无法解读结果
- Agent 无法从故障中恢复
指南
- 编写能够说明用途、使用时机和返回内容的描述
- 使用整合来减少歧义
- 实现响应格式选项以提高 token 效率
- 设计有助于 Agent 恢复的错误消息
- 建立并遵循一致的命名约定
- 限制工具数量，并使用命名空间进行组织
- 使用实际的 Agent 交互测试工具设计
- 根据观察到的失败模式进行迭代
- 质疑每个工具究竟是在赋能模型，还是在限制模型
- 优先使用基础、通用的工具，而非专用封装
- 重视文档质量，而非工具复杂度
- 构建能从模型改进中获益的最小化架构
集成
此技能与以下内容相关：
- context-fundamentals - 工具如何与上下文交互
- multi-agent-patterns - 为每个 Agent 配备专用工具
- evaluation - 评估工具的有效性
参考资料
本文未附带名为 Best Practices Reference 和 Architectural Reduction Case Study 的资料。应将精简视为一种设计假设，并在相同任务、权限、故障／恢复率和成本条件下，将其与结构化工具进行比较。
此合集中的相关技能：
- context-fundamentals - 工具与上下文的交互
- evaluation - 工具测试模式
外部资源：
- MCP（Model Context Protocol）文档
- 框架工具约定
- 面向 Agent 的 API 设计最佳实践
- Vercel d0 Agent 架构案例研究
技能元数据
创建时间：2025-12-20 最后更新：2025-12-23 作者：Agent Skills for Context Engineering Contributors 版本：1.1.0
限制
- 仅当任务明确符合上述范围时，才使用此技能。
- 不要将输出视为针对特定环境进行验证、测试或专家审查的替代品。
- 如果缺少必需的输入、权限、安全边界或成功标准，请暂停并请求澄清。