# Tool Design

> 构建智能体可高效使用的工具，包括架构精简模式。适用于为智能体系统创建新工具、调试工具相关故障或误用、优化现有工具集以提升智能体性能。

- Skill: `kscz0000/tool-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kscz0000/tool-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/tool-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/tool-design

---


## 适用场景

构建智能体可高效使用的工具，包括架构精简模式

适用于构建智能体可高效使用的工具，包括架构精简模式的场景。

# 智能体工具设计

工具是智能体与世界交互的主要机制。它定义了确定性系统与非确定性智能体之间的契约。与面向开发者的传统软件 API 不同，工具 API 必须为语言模型而设计——模型需要推理意图、推断参数值、从自然语言请求生成调用。糟糕的工具设计会产生再多提示词工程也无法修复的失败模式。有效的工具设计遵循特定原则，充分考虑智能体感知和使用工具的方式。

## 何时使用
以下场景激活此技能：
- 为智能体系统创建新工具
- 调试工具相关故障或误用
- 优化现有工具集以提升智能体性能
- 从零设计工具 API
- 评估第三方工具的智能体集成
- 统一代码库中的工具规范

## 核心概念

工具是确定性系统与非确定性智能体之间的契约。整合原则指出：如果人类工程师无法明确判断某个场景该用哪个工具，就不能指望智能体做得更好。有效的工具描述是塑造智能体行为的提示词工程。

核心原则包括：回答"做什么、何时用、返回什么"的清晰描述；平衡完整性与 token 效率的响应格式；支持恢复的错误消息；降低认知负荷的统一规范。

## 详细主题

### 工具-智能体接口

**工具即契约**
工具是确定性系统与非确定性智能体之间的契约。人类调用 API 时理解契约并发出恰当请求。智能体必须从描述中推断契约，并生成符合预期格式的调用。

这种根本差异要求重新思考 API 设计。契约必须无歧义，示例必须说明预期模式，错误消息必须引导修正。工具定义中的每个歧义都是潜在的失败点。

**工具描述即提示词**
工具描述被加载到智能体上下文中，共同引导行为。描述不仅仅是文档——它们是塑造智能体工具使用推理方式的提示词工程。

像"搜索数据库"这样模糊的描述加上晦涩的参数名，会迫使智能体猜测。优化后的描述包含使用场景、示例和默认值。描述应回答：工具做什么、何时使用、产出什么。

**命名空间与组织**
随着工具集增长，组织变得至关重要。命名空间将相关工具归组到公共前缀下，帮助智能体在正确时机选择合适工具。

命名空间在功能之间创建清晰边界。智能体需要数据库信息时路由到数据库命名空间，需要网络搜索时路由到网络命名空间。

### 整合原则

**单一综合工具**
整合原则指出：如果人类工程师无法明确判断某个场景该用哪个工具，就不能指望智能体做得更好。因此应优先选择单一综合工具，而非多个细分工具。

与其分别实现 list_users、list_events 和 create_event，不如实现一个 schedule_event 来查找空闲时间并安排日程。综合工具在内部处理完整工作流，无需智能体串联多个调用。

**整合为何有效**
智能体的上下文和注意力有限。工具集中的每个工具都在工具选择阶段争夺注意力。每个工具都增加消耗上下文预算的描述 token。功能重叠会产生选择歧义。

整合通过消除冗余描述减少 token 消耗，通过单一工具覆盖每个工作流消除歧义，通过缩小有效工具集降低选择复杂度。

**何时不应整合**
整合并非万能。行为本质不同的工具应保持分离。在不同场景使用的工具适合分开。可能被独立调用的工具不应强行捆绑。

### 架构精简

将整合原则推向极致，就是架构精简：移除大部分专用工具，改用原始的通用能力。生产证据表明，这种方式可以超越复杂的多工具架构。

**文件系统智能体模式**
与其为数据探索、模式查找和查询验证构建自定义工具，不如通过单一命令执行工具提供直接的文件系统访问。智能体使用标准 Unix 工具（grep、cat、find、ls）来探索、理解和操作系统。

这之所以有效，因为：
1. 文件系统是模型深入理解的成熟抽象
2. 标准工具行为可预测、文档完善
3. 智能体可以灵活组合原语，而非受限于预定义工作流
4. 文件中的良好文档取代了摘要工具的需求

**精简何时优于复杂**
精简有效的条件：
- 数据层文档完善且结构一致
- 模型具备足够的推理能力应对复杂性
- 专用工具在限制而非赋能模型
- 维护脚手架的时间超过改善结果的时间

精简失败的条件：
- 底层数据混乱、不一致或文档缺失
- 领域需要模型不具备的专业知识
- 安全约束要求限制智能体的操作
- 操作确实复杂，结构化工作流更有价值

**停止约束推理**
常见的反模式是构建工具来"保护"模型免受复杂性困扰。预过滤上下文、约束选项、用验证逻辑包装交互。随着模型进步，这些护栏往往变成负担。

关键问题：你的工具是在赋能新能力，还是在约束模型本身能处理的推理？

**为未来模型构建**
模型进步速度超过工具跟进速度。为当前模型优化的架构可能对未来模型过度约束。构建能从模型改进中受益的精简架构，而非锁定当前局限的复杂架构。

参见架构精简案例研究了解生产证据。

### 工具描述工程

**描述结构**
有效的工具描述回答四个问题：

工具做什么？清晰、具体的功能描述。避免"帮助处理"或"可用于"等模糊语言。准确说明工具完成什么。

何时使用？具体的触发条件和场景。包括直接触发（"用户询问定价"）和间接信号（"需要当前市场费率"）。

接受什么输入？带类型、约束和默认值的参数描述。解释每个参数控制什么。

返回什么？输出格式和结构。包含成功响应和错误条件的示例。

**默认参数选择**
默认值应反映常见用例。通过消除不必要的参数指定来减轻智能体负担。防止因省略参数导致的错误。

### 响应格式优化

工具响应大小显著影响上下文使用。实现响应格式选项让智能体控制详细程度。

简洁格式仅返回必要字段，适用于确认或基本信息。详细格式返回包含所有字段的完整对象，适用于需要完整上下文的决策。

在工具描述中包含何时使用每种格式的指导。智能体学会根据任务需求选择合适格式。

### 错误消息设计

错误消息服务于两类受众：调试问题的开发者和从失败中恢复的智能体。对智能体而言，错误消息必须可操作。必须告诉智能体出了什么问题以及如何修正。

设计支持恢复的错误消息。可重试错误包含重试指导，输入错误包含修正格式，缺失数据包含所需内容。

### 工具定义模式

所有工具使用统一的模式。建立命名规范：工具名使用动词-名词模式，跨工具保持一致的参数名，统一返回字段名。

### 工具集设计

研究表明工具描述重叠会导致模型困惑。更多工具不一定带来更好结果。合理指导原则是大多数应用使用 10-20 个工具。如需更多，使用命名空间创建逻辑分组。

实现机制帮助智能体选择正确工具：工具分组、基于示例的选择、以及将伞形工具路由到专用子工具的层级结构。

### MCP 工具命名要求

使用 MCP（模型上下文协议）工具时，始终使用完全限定的工具名以避免"工具未找到"错误。

格式：`ServerName:tool_name`

```python
# 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 服务器可用时。建立在所有工具引用中包含服务器上下文的命名规范。

### 使用智能体优化工具

Claude 可以优化自己的工具。给定工具和观察到的失败模式后，它能诊断问题并提出改进建议。生产测试表明，通过帮助未来智能体避免错误，这种方式可将任务完成时间减少 40%。

**工具测试智能体模式**：

```python
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)
```

这形成反馈循环：使用工具的智能体生成失败数据，智能体随后用这些数据改进工具描述，从而减少未来失败。

### 测试工具设计

根据以下标准评估工具设计：无歧义、完整性、可恢复性、效率和一致性。通过呈现代表性智能体请求并评估生成的工具调用来测试工具。

## 实践指导

### 应避免的反模式

模糊描述："搜索数据库中的客户信息"留下太多未解答的问题。

晦涩参数名：参数命名为 x、val 或 param1 会迫使智能体猜测含义。

缺失错误处理：以通用错误失败的工具无法提供恢复指导。

命名不一致：某些工具用 id、某些用 identifier、某些用 customer_id 会造成混乱。

### 工具选择框架

设计工具集时：
1. 识别智能体必须完成的不同工作流
2. 将相关操作分组到综合工具中
3. 确保每个工具目的清晰明确
4. 记录错误情况和恢复路径
5. 用实际智能体交互测试

## 示例

**示例 1：良好设计的工具**
```python
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：糟糕的工具设计**

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

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

**此设计的问题：**

1. **名称模糊**："search"有歧义——搜索什么，出于什么目的？
2. **参数缺失**：什么数据库？query 应该是什么格式？
3. **无返回描述**：此函数返回什么？列表？字符串？错误处理？
4. **无使用场景**：智能体何时应使用此工具而非其他工具？
5. **无错误处理**：数据库不可用时会发生什么？

**失败模式：**
- 智能体可能在应使用更具体工具时调用此工具
- 智能体无法确定正确的查询格式
- 智能体无法解释结果
- 智能体无法从失败中恢复

## 指导原则

1. 编写回答"做什么、何时用、返回什么"的描述
2. 使用整合减少歧义
3. 实现响应格式选项以优化 token 效率
4. 为智能体恢复设计错误消息
5. 建立并遵循一致的命名规范
6. 限制工具数量并使用命名空间组织
7. 用实际智能体交互测试工具设计
8. 基于观察到的失败模式迭代
9. 质疑每个工具是在赋能还是约束模型
10. 优先使用原始通用工具而非专用包装器
11. 投资文档质量而非工具复杂度
12. 构建能从模型改进中受益的精简架构

## 集成

此技能连接：
- context-fundamentals - 工具与上下文的交互
- multi-agent-patterns - 每个智能体的专用工具
- evaluation - 评估工具有效性

## 参考

内部参考：
- 最佳实践参考 - 详细的工具设计指南
- 架构精简案例研究 - 工具极简主义的生产证据

本系列相关技能：
- context-fundamentals - 工具上下文交互
- evaluation - 工具测试模式

外部资源：
- MCP（模型上下文协议）文档
- 框架工具规范
- 面向智能体的 API 设计最佳实践
- Vercel d0 智能体架构案例研究

---

## 技能元数据

**创建日期**: 2025-12-20
**最后更新**: 2025-12-23
**作者**: Agent Skills for Context Engineering Contributors
**版本**: 1.1.0

## 限制
- 仅在任务明确匹配上述范围时使用此技能。
- 不要将输出视为替代环境特定的验证、测试或专家审查。
- 如果所需输入、权限、安全边界或成功标准缺失，停下来请求澄清。