上一篇的 Agent Loop 里，有一步叫「执行工具」。这一篇把它拆开讲：模型是怎么知道有哪些工具、怎么「调用」工具的，以及怎样设计出好用的工具。
一、一个常见误解
很多人以为 Function Calling 是模型自己去执行代码。其实不是。模型只负责提出请求，真正执行的是你的程序。
整个过程是这样的：
- 你在请求中告诉模型：有哪些工具可用，每个工具做什么、需要什么参数。
- 模型判断需要用某个工具时，输出一个结构化的调用请求：工具名 + 参数。
- 你的程序解析这个请求，执行对应的函数，拿到结果。
- 你把结果回填给模型，模型继续。
模型从头到尾都碰不到你的数据库和服务器，它看到的只有工具定义和你回填的结果。这一点对安全设计非常重要，第 18 篇会再讲。
二、工具定义的三要素
一个工具定义包含三部分：
{
"name": "query_orders",
"description": "查询指定时间范围内的订单数量，按小时汇总。用于分析下单量的变化趋势。时间范围最长 7 天；如需更长时间，请分多次查询。",
"input_schema": {
"type": "object",
"properties": {
"start": {"type": "string", "description": "开始时间，格式 YYYY-MM-DD HH:MM"},
"end": {"type": "string", "description": "结束时间，格式同上"},
"channel": {"type": "string", "enum": ["web", "app", "all"],
"description": "下单渠道，默认 all"}
},
"required": ["start", "end"]
}
}- name：工具名，简短、有意义，使用英文和下划线。
- description：给模型看的说明书。这是最重要的部分，模型完全靠它判断什么时候用、怎么用。
- 参数 Schema：用 JSON Schema 描述参数的类型、格式、是否必填、可选值。
（字段名各家 API 略有不同，比如有的叫 parameters，有的叫 input_schema，结构是一样的。）
三、description 怎么写
把模型当成一个聪明但第一天上班的新同事，description 要告诉它：
- 这个工具做什么：一句话说清楚。
- 什么时候该用：尤其是有多个相似工具时，要说明区别。
- 有什么限制：时间范围上限、返回条数上限、调用成本高不高。
- 返回什么：让模型预期结果的形态。
对比一下：
| 写法 | description |
|---|---|
| 差 | 查询订单 |
| 好 | 查询指定时间范围内的订单数量，按小时汇总，返回每小时订单数和与昨日同期的对比。用于分析下单量趋势。如果需要具体订单明细，请使用 get_order_detail。 |
工具调用不准确时，第一反应应该是改 description，而不是改模型。
四、调用 ID：把请求和结果对上
模型的每个工具调用请求都带一个唯一 ID，回填结果时要带上同一个 ID。这在两种情况下特别重要：
- 并行调用：模型一次请求了多个工具，比如同时查 web 和 app 两个渠道的订单。结果靠 ID 和请求一一对应。
- 历史回溯：多轮之后，模型需要知道哪个结果是哪次调用返回的。
互不依赖的查询，模型通常会自动并行请求。你的程序应该支持并发执行这些调用，能明显减少等待时间。
五、工具设计原则
1. 粒度适中
工具太细，模型要调用很多次才能完成一件事，慢且容易出错；工具太粗，比如一个万能的「执行 SQL」，灵活但难以控制，也容易出安全问题。好的粒度是对应一个有意义的业务动作，比如「查询某时段订单量」「统计接口错误率」。
2. 返回值要精简
工具结果会进入上下文，占用 token。不要返回完整的原始数据：
- 只返回模型做决策需要的字段；
- 大量数据先汇总再返回；
- 结果过多时截断，并告诉模型「共 5000 条，仅显示前 20 条，可加筛选条件缩小范围」。
3. 错误信息要能指导下一步
工具出错时，把错误作为结果返回给模型，而不是让程序崩溃。错误信息要让模型知道怎么改正：
| 差 | 好 |
|---|---|
| Error: invalid param | 时间范围不能超过 7 天，你传入的是 30 天。请缩小范围或分多次查询。 |
4. 区分只读和有副作用的工具
查询类工具可以放心让模型自主调用；修改、删除、发送类工具要单独标记，必要时加人工确认。
六、工具数量多了怎么办
每个工具定义都会占用上下文，工具太多还会让模型选错。经验上：
- 工具在几个到二三十个之间，模型一般都能处理好。
- 工具很多时，可以按场景分组，只加载当前任务需要的那组；或者提供一个「搜索工具」的工具，让模型按需发现。
- 功能相近的工具尽量合并，用参数区分。
第 12 篇讲的 MCP 和第 14 篇讲的 Skills，本质上都在解决「工具怎么组织、怎么按需加载」这个问题。
本篇小结
- 模型只提出调用请求，执行在你的程序里。
- 工具定义 = name + description + 参数 Schema，description 最关键。
- 调用 ID 用于把请求和结果对应起来，支持并行调用。
- 设计原则：粒度适中、返回精简、错误信息可指导下一步、区分只读与写操作。
思考与练习
- 给「查询某个商品过去 1 小时的订单量」设计一个完整的工具定义，包括 name、description 和参数 Schema。
- 如果你有「查订单汇总」和「查订单明细」两个工具，description 怎么写才能让模型不选错？
上一篇：AI Agent原理篇04：Agent Loop：感知-思考-行动循环与 ReAct
下一篇：AI Agent原理篇06：结构化输出与解析容错
返回系列总目录