4-2 工具设计规范

好工具的四个特征

• ✅ 单一职责：一个工具只做一件事，不要把搜索和处理合并在一起
• ✅ 清晰的输入输出：参数类型明确，返回值格式固定
• ✅ 幂等性：同样的输入多次调用结果一样（或至少不会产生副作用）
• ✅ 有错误返回：失败时返回有意义的错误信息，而不是崩溃或返回空

工具描述的写法至关重要

AI根据工具的description决定是否调用、如何调用。描述写得好，AI才能正确使用。

# ❌ 错误：描述太模糊
{
  "name": "search",
  "description": "搜索一些东西"
}

# ✅ 正确：描述清晰说明用途和参数含义
{
  "name": "web_search",
  "description": "在互联网上搜索信息。适合查询最新新闻、实时数据、不在训练数据中的信息。返回搜索结果列表，每条包含标题、URL和摘要。",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "搜索关键词，建议用具体的词语而非模糊表达"
      },
      "limit": {
        "type": "integer",
        "description": "返回结果数量，默认5，最大10",
        "default": 5
      }
    },
    "required": ["query"]
  }
}

工具粒度设计

太细（调用次数爆炸）

# ❌ 把文件操作拆得太细
read_file_first_line()
read_file_second_line()
read_file_nth_line()
→ 读100行要调用100次

太粗（灵活性差）

# ❌ 把所有数据库操作合并成一个工具
database_operation(operation_type, table, data, where, order_by, limit...)
→ 参数复杂，AI不知道怎么填，经常填错

合适的粒度

# ✅ 一个工具对应一个清晰的业务操作
read_file(path, offset, limit)     # 读文件，支持分页
write_file(path, content)           # 写文件
search_files(pattern, path)         # 搜索文件

5个好坏对比示例

工具的description是给AI看的说明书。写得好，AI能准确调用；写得差，AI会乱猜参数，导致错误或需要多次重试。