工具定义指南

工具是 Agent 技能的「手」——通过工具声明，Agent 可以调用外部 API、发送通知、执行定时任务等。本文教你如何定义清晰、准确的工具声明。

什么是工具声明

工具声明是 tools.json 文件，用 JSON Schema 格式描述 Agent 可以调用的每个工具。Agent 根据工具描述自动判断何时调用哪个工具。

[
  {
    "name": "get_weather",
    "description": "获取指定城市的实时天气数据",
    "parameters": {
      "type": "object",
      "required": ["city"],
      "properties": {
        "city": {
          "type": "string",
          "description": "城市名称，如 'Beijing'"
        }
      }
    }
  }
]

工具定义结构

每个工具包含三个必填字段：

字段类型说明
namestring工具唯一标识，英文，下划线分隔（如 get_weather）
descriptionstring工具功能描述——这是 Agent 判断何时调用的唯一依据
parametersobjectJSON Schema 格式的参数定义

参数定义

参数用 JSON Schema 规范定义，支持以下类型：

基础类型

{
  "name": "send_notification",
  "description": "向用户发送推送通知",
  "parameters": {
    "type": "object",
    "required": ["message"],
    "properties": {
      "message": {
        "type": "string",
        "description": "推送消息内容"
      },
      "priority": {
        "type": "string",
        "enum": ["low", "normal", "high"],
        "description": "推送优先级",
        "default": "normal"
      }
    }
  }
}

参数类型一览

类型示例说明
string"Beijing"文本字符串
number25.5数字
integer10整数
booleantrue布尔值
enum["low", "normal", "high"]限定可选值
array["tag1", "tag2"]数组

参数字段说明

字段说明
type参数类型
description参数说明——Agent 据此理解参数含义
required顶层数组，列出必填参数
default默认值
enum限定可选值（用于下拉选择）
minimum / maximum数值范围（number/integer）

编写高质量描述

工具描述是 Agent 判断何时调用的唯一依据。 描述写得不好，Agent 要么不调用，要么乱调用。

命名规范

✅ 好的命名：

get_weather       # 动词+名词，清晰
send_notification # 动词+名词
search_files      # 动词+名词

❌ 差的命名：

do_stuff   # 含义不明
tool1      # 无意义
weather    # 只有名词，不知道要做什么

描述规范

✅ 好的描述：

{
  "description": "获取指定城市的实时天气数据，返回温度、湿度、风速和天气状况"
}

❌ 差的描述：

{
  "description": "天气工具"
}

原则：描述说清楚「输入什么 → 输出什么」，Agent 才能准确判断调用时机。

常用工具模式

模式 1：查询类工具

获取外部数据，通常对应 HTTP GET 请求。

{
  "name": "get_stock_price",
  "description": "获取指定股票代码的实时价格",
  "parameters": {
    "type": "object",
    "required": ["symbol"],
    "properties": {
      "symbol": {
        "type": "string",
        "description": "股票代码，如 'AAPL'、'600519.SH'"
      }
    }
  }
}

模式 2：操作类工具

执行操作或发送数据，通常对应 HTTP POST/PUT 请求。

{
  "name": "create_notion_page",
  "description": "在 Notion 数据库中创建新页面",
  "parameters": {
    "type": "object",
    "required": ["title", "content"],
    "properties": {
      "title": {
        "type": "string",
        "description": "页面标题"
      },
      "content": {
        "type": "string",
        "description": "页面内容（Markdown 格式）"
      },
      "database_id": {
        "type": "string",
        "description": "目标数据库 ID"
      }
    }
  }
}

模式 3：通知类工具

发送推送通知或消息。

{
  "name": "send_notification",
  "description": "向用户发送推送通知，用于重要信息提醒",
  "parameters": {
    "type": "object",
    "required": ["message"],
    "properties": {
      "message": {
        "type": "string",
        "description": "推送消息内容"
      },
      "priority": {
        "type": "string",
        "enum": ["low", "normal", "high"],
        "description": "推送优先级，high 会触发强提醒",
        "default": "normal"
      }
    }
  }
}

模式 4：搜索类工具

搜索和过滤数据。

{
  "name": "search_files",
  "description": "在设备文件系统中搜索文件",
  "parameters": {
    "type": "object",
    "required": ["query"],
    "properties": {
      "query": {
        "type": "string",
        "description": "搜索关键词"
      },
      "file_type": {
        "type": "string",
        "enum": ["all", "document", "image", "code", "audio"],
        "description": "文件类型过滤",
        "default": "all"
      },
      "max_results": {
        "type": "integer",
        "description": "最大返回数量",
        "default": 10,
        "minimum": 1,
        "maximum": 50
      }
    }
  }
}

工具数量建议

技能复杂度建议工具数示例
⭐ 简单1-2 个天气预报：获取天气 + 推送通知
⭐⭐ 中等3-5 个会议纪要：录音转文字 + 生成纪要 + 发送邮件 + 创建日历
⭐⭐⭐ 复杂5-8 个代码审查：获取 PR + 分析代码 + 运行检查 + 生成报告 + 评论 PR

原则：工具不是越多越好。每个工具必须有明确的调用场景，Agent 能准确判断何时调用。

工具定义自检清单

写完 tools.json 后，逐条检查：

  1. 每个工具名称是动词+名词（如 get_weather 而非 weather）
  2. 描述说明了输入和输出（Agent 知道什么时候调用）
  3. 必填参数标记了 required
  4. 每个参数都有 description
  5. 枚举类型用了 enum 而非在描述中列举
  6. 默认值合理，用户不填也能用
  7. 工具数量不超过 8 个（太多 Agent 难以选择）

← Prompt 编写最佳实践 | 配置参数设计 →

返回文档中心