name: tool-design description: 设计可供智能体有效使用的工具。在创建新的智能体工具、调试与工具相关的故障或优化现有工具集时使用。
智能体工具设计
工具是智能体与世界交互的主要机制。它们定义了确定性系统与非确定性智能体之间的契约。与为开发者设计的传统软件API不同，工具API必须为能够推理意图、推断参数值并根据自然语言请求生成调用的语言模型而设计。糟糕的工具设计会产生任何提示工程都无法修复的故障模式。有效的工具设计遵循特定的原则，这些原则考虑了智能体如何感知和使用工具。
何时激活
在以下情况下激活此技能：
- 为智能体系统创建新工具时
- 调试与工具相关的故障或误用时
- 为提升智能体性能而优化现有工具集时
- 从头开始设计工具API时
- 评估用于智能体集成的第三方工具时
- 在代码库中标准化工具约定时
核心概念
工具是确定性系统与非确定性智能体之间的契约。整合原则指出：如果人类工程师无法明确说明在给定情况下应使用哪个工具，那么就不能期望智能体做得更好。有效的工具描述是塑造智能体行为的提示工程。
关键原则包括：清晰的描述，回答做什么、何时用以及返回什么；平衡完整性和令牌效率的响应格式；支持恢复的错误消息；以及减少认知负荷的一致约定。
详细主题
工具-智能体接口
工具即契约 工具是确定性系统与非确定性智能体之间的契约。当人类调用API时，他们理解契约并发出适当的请求。智能体必须从描述中推断契约，并生成符合预期格式的调用。
这种根本差异要求重新思考API设计。契约必须明确无误，示例必须说明预期模式，错误消息必须指导纠正。工具定义中的每一个模糊点都成为一个潜在的故障模式。
工具描述即提示 工具描述被加载到智能体上下文中，并共同引导其行为。这些描述不仅仅是文档——它们是塑造智能体如何推理工具使用的提示工程。
像“搜索数据库”这样带有神秘参数名称的糟糕描述会迫使智能体猜测。优化的描述包括使用上下文、示例和默认值。描述应回答：工具做什么、何时使用它以及它产生什么。
命名空间与组织 随着工具集合的增长，组织变得至关重要。命名空间将相关工具分组到公共前缀下，帮助智能体在正确的时间选择合适的工具。
命名空间在功能之间创建了清晰的边界。当智能体需要数据库信息时，它路由到数据库命名空间。当它需要网络搜索时，它路由到网络命名空间。
整合原则
单一综合性工具 整合原则指出：如果人类工程师无法明确说明在给定情况下应使用哪个工具，那么就不能期望智能体做得更好。这导致了对单一综合性工具的偏好，而不是多个狭窄的工具。
与其实现 list_users、list_events 和 create_event，不如实现 schedule_event，它能查找可用性并进行安排。综合性工具在内部处理完整的工作流程，而不是要求智能体链接多个调用。
整合为何有效 智能体的上下文和注意力有限。集合中的每个工具在工具选择阶段都会争夺注意力。每个工具都会添加消耗上下文预算的描述令牌。功能重叠会引发关于使用哪个工具的模糊性。
整合通过消除冗余描述来减少令牌消耗。它通过让一个工具覆盖每个工作流程来消除模糊性。它通过缩小有效工具集来降低工具选择的复杂性。
何时不应整合 整合并非普遍正确。具有根本不同行为的工具应保持分离。在不同上下文中使用的工具受益于分离。可能被独立调用的工具不应被强行捆绑。
工具描述工程
描述结构 有效的工具描述回答四个问题：
工具做什么？ 清晰、具体地描述功能。避免使用“有助于”或“可用于”等模糊语言。准确说明工具实现了什么。
何时应该使用它？ 具体的触发条件和上下文。包括直接触发（“用户询问价格”）和间接信号（“需要当前市场利率”）。
它接受什么输入？ 包含类型、约束和默认值的参数描述。解释每个参数控制什么。
它返回什么？ 输出格式和结构。包括成功响应和错误条件的示例。
默认参数选择 默认值应反映常见用例。它们通过消除不必要的参数指定来减轻智能体的负担。它们防止因省略参数而导致的错误。
响应格式优化
工具响应大小显著影响上下文使用。实现响应格式选项可以让智能体控制详细程度。
简洁格式仅返回基本字段，适用于确认或基本信息。详细格式返回包含所有字段的完整对象，适用于需要完整上下文进行决策的情况。
在工具描述中包含关于何时使用每种格式的指导。智能体学会根据任务要求选择合适的格式。
错误消息设计
错误消息服务于两个受众：调试问题的开发者和从故障中恢复的智能体。对于智能体，错误消息必须是可操作的。它们必须告诉智能体出了什么问题以及如何纠正。
设计能够支持恢复的错误消息。对于可重试的错误，包含重试指导。对于输入错误，包含正确的格式。对于缺失的数据，说明需要什么。
工具定义模式
在所有工具中使用一致的模式。建立命名约定：工具名称采用动词-名词模式，跨工具的参数名称一致，返回字段名称一致。
工具集合设计
研究表明，工具描述重叠会导致模型混淆。更多的工具并不总是带来更好的结果。一个合理的指导原则是，大多数应用程序使用10-20个工具。如果需要更多，使用命名空间创建逻辑分组。
实现帮助智能体选择正确工具的机制：工具分组、基于示例的选择以及具有将请求路由到专门子工具的伞状工具的层次结构。
MCP 工具命名要求
使用 MCP（模型上下文协议）工具时，始终使用完全限定的工具名称，以避免“找不到工具”错误。
格式：ServerName:tool_name
# 正确：完全限定的名称
"使用 BigQuery:bigquery_schema 工具来检索表模式。"
"使用 GitHub:create_issue 工具来创建问题。"
# 错误：非限定名称
"使用 bigquery_schema 工具..." # 当有多个服务器时可能会失败
如果没有服务器前缀，智能体可能无法定位工具，尤其是在有多个MCP服务器可用时。建立在所有工具引用中都包含服务器上下文的命名约定。
使用智能体优化工具
Claude 可以优化自己的工具。当给定一个工具并观察到故障模式时，它会诊断问题并提出改进建议。生产测试表明，这种方法通过帮助未来的智能体避免错误，实现了任务完成时间减少40%。
工具测试智能体模式：
def optimize_tool_description(tool_spec, failure_examples):
"""
使用智能体分析工具故障并改进描述。
流程：
1. 智能体尝试在各种任务中使用工具
2. 收集故障模式和摩擦点
3. 智能体分析故障并提出改进建议
4. 针对相同任务测试改进后的描述
"""
prompt = f"""
分析此工具规范和观察到的故障。
工具：{tool_spec}
观察到的故障：
{failure_examples}
识别：
1. 为什么智能体在使用此工具时失败
2. 描述中缺少什么信息
3. 哪些模糊性导致了错误使用
提出一个解决这些问题的改进工具描述。
"""
return get_agent_response(prompt)
这创建了一个反馈循环：使用工具的智能体生成故障数据，然后智能体使用这些数据来改进工具描述，从而减少未来的故障。
测试工具设计
根据标准评估工具设计：明确性、完整性、可恢复性、效率和一致性。通过呈现具有代表性的智能体请求并评估由此产生的工具调用来测试工具。
实用指导
要避免的反模式
模糊描述：“在数据库中搜索客户信息”留下了太多未回答的问题。
神秘参数名称：名为 x、val 或 param1 的参数迫使智能体猜测含义。
缺少错误处理：因通用错误而失败的工具不提供任何恢复指导。
命名不一致：在某些工具中使用 id，在其他工具中使用 identifier，在某些工具中使用 customer_id，会造成混淆。
工具选择框架
设计工具集合时：
- 识别智能体必须完成的不同工作流程
- 将相关操作分组到综合性工具中
- 确保每个工具都有明确、无歧义的目的
- 记录错误情况和恢复路径
- 通过实际的智能体交互进行测试
示例
示例 1：设计良好的工具
def get_customer(customer_id: str, format: str = "concise"):
"""
通过ID检索客户信息。
使用时机：
- 用户询问特定客户详情时
- 需要客户上下文进行决策时
- 验证客户身份时
参数：
customer_id: 格式 "CUST-######" (例如 "CUST-000001")
format: "concise" 表示关键字段，"detailed" 表示完整记录
返回：
包含请求字段的客户对象
错误：
NOT_FOUND: 未找到客户ID
INVALID_FORMAT: ID 必须匹配 CUST-###### 模式
"""
示例 2：糟糕的工具设计
此示例展示了几个工具设计的反模式：
def search(query):
"""搜索数据库。"""
pass
此设计的问题：
- 名称模糊：“search”是模糊的——搜索什么，出于什么目的？
- 缺少参数：什么数据库？查询应采用什么格式？
- 没有返回描述：此函数返回什么？列表？字符串？错误处理？
- 没有使用上下文：智能体何时应使用此工具而不是其他工具？
- 没有错误处理：如果数据库不可用会发生什么？
故障模式：
- 智能体可能在本应使用更具体工具时调用此工具
- 智能体无法确定正确的查询格式
- 智能体无法解释结果
- 智能体无法从故障中恢复
指南
- 编写能回答做什么、何时用以及返回什么的描述
- 使用整合来减少模糊性
- 实现响应格式选项以提高令牌效率
- 为智能体恢复设计错误消息
- 建立并遵循一致的命名约定
- 限制工具数量并使用命名空间进行组织
- 通过实际的智能体交互测试工具设计
- 根据观察到的故障模式进行迭代
集成
此技能连接到：
- context-fundamentals - 工具如何与上下文交互
- multi-agent-patterns - 每个智能体的专用工具
- evaluation - 评估工具有效性
参考文献
内部参考：
- 最佳实践参考 - 详细的工具设计指南
此集合中的相关技能：
- context-fundamentals - 工具上下文交互
- evaluation - 工具测试模式
外部资源：
- MCP（模型上下文协议）文档
- 框架工具约定
- 面向智能体的API设计最佳实践
技能元数据
创建时间：2025-12-20 最后更新：2025-12-20 作者：Agent Skills for Context Engineering Contributors 版本：1.0.0