工具描述怎么写？为什么说工具说明就是 Prompt 的一部分？

简化版

模型决定调不调一个工具、传什么参数，依据只有三样东西：工具名、工具描述、参数 Schema。它们随每次请求发给模型，本质上就是 Prompt 的一部分，写得含糊，模型就会漏调、错调、传错参数。一段好的描述要回答四个问题：这个工具做什么、什么时候该调、什么时候不该调、返回结果怎么读；参数说明要写清取值范围和格式，而且描述和 Schema 必须说同一件事（描述里写「不传表示不限」，Schema 里就要标成非必填）。描述改完要能立即看到模型实际收到的内容，并用调用日志验证效果。

详细版

一个工具发给模型的样子：

{
  "type": "function",
  "function": {
    "name": "query_distance",
    "description": "查询两个点位之间的直线距离、路程和预计车程。写入行程前用它确认同一天的点位不会太远。不要用它穷举搜索最优顺序，应先按城区把点位分组，再验证组内顺序。",
    "parameters": {
      "type": "object",
      "properties": {
        "fromPoiId": {"type": "integer", "description": "起点点位ID，取自点位查询工具的返回"},
        "toPoiId": {"type": "integer", "description": "终点点位ID，取自点位查询工具的返回"}
      },
      "required": ["fromPoiId", "toPoiId"]
    }
  }
}

描述要覆盖的内容：

要素	回答的问题	缺了会怎样
用途	这个工具做什么	模型不知道它能解决什么问题
调用时机	什么时候该调、调用顺序	该调的时候不调，或调用顺序乱
禁止用法	什么时候不该调	被拿去穷举、刷调用次数
返回解读	返回字段是什么意思、下一步怎么做	读错结果，或看到子集以为是全部
参数说明	每个参数的含义、取值、来源	编造参数值、格式对不上

完整版教学

一、模型看到的只有名称、描述和 Schema

模型并不知道工具背后是哪张表、哪个方法。每次请求里，应用把工具清单作为 tools 数组发给模型，模型能读到的只有：

name         工具名：query_distance
description  一段自然语言：做什么、什么时候用、什么时候别用
parameters   JSON Schema：有哪些参数、类型、是否必填、每个参数的说明

所以工具描述和系统提示词是同一类东西：都是模型推理时读到的文字，都会影响它的决策，改描述就是在调 Prompt。区别只在于描述是「按工具拆开」的，每个工具只管自己那一段。

记忆钩子：模型看不到你的代码，只看得到你的说明书。说明书写成什么样，它就按什么理解。

二、描述要回答的四个问题

以一个点位查询工具为例，对比一下：

差：查询点位。

好：在本次候选池里按城市、兴趣标签、城区和最长游玩时长筛点位。
    只返回候选池内的点位，池外的资源查不到。
    hasMore 为 true 时说明还有没返回的候选，可以换标签或城区条件再查一次；
    不要用本工具穷举翻页，选不到合适的就按现有候选安排。

「好」的版本回答了四件事：

问题	对应的句子
做什么	在候选池里按城市、标签、城区、时长筛点位
边界在哪	只返回候选池内的点位，池外查不到
返回怎么读	hasMore 为 true 说明还有没返回的
下一步和禁止用法	换条件再查；不要穷举翻页

其中「什么时候不该调」最容易被忽略。模型有一个倾向：手里有工具就想用，尤其是能返回确定答案的检测类、计算类工具，它会拿来反复试。明确写出禁止用法，比事后用调用次数上限拦截更省成本。

三、参数说明：写清取值和来源

参数是模型生成的，Schema 只能约束类型，约束不了取值。常见问题和写法：

问题	差的写法	好的写法
枚举值	交通方式	取值：飞机/高铁/动车/大巴
格式	日期	日期，格式 yyyy-MM-dd
来源	城市ID	目的地城市ID，取自上下文查询工具返回的 cityRoute
可选语义	城区	城区或商圈名；不传表示不限
多值	标签	多个用逗号分隔，例如历史,摄影；命中任意一个即算匹配

「来源」这一项很关键：ID 类参数写明从哪个工具的返回里取，模型就不会凭空编一个数字。

四、描述和 Schema 必须说同一件事

一个常见的不一致：

描述：area 城区名，不传表示不限
Schema：required: ["destinationId", "area"]

描述说可以不传，Schema 却把它列为必填，模型每次都得硬塞一个值，于是出现「area = 全部」「area = 不限」这类参数，工具按字面去匹配，一条都查不到。用注解生成 Schema 的框架里，参数默认往往是必填的，写了「不传表示不限」就要同时显式声明非必填。

五、描述的长度也是成本

描述每一轮都会随请求发给模型。粗算一下：

8 个工具 × 每个描述和参数约 150 token ≈ 1200 token
一次编排 40 轮往返 × 1200 token ≈ 48000 token 只花在工具清单上

所以描述要写准，但不要写成说明文档：业务背景、实现细节、表结构都不需要。一句用途、一两句调用时机和禁止用法、每个参数一句说明，通常就够了。工具数量多时，还可以只把当前任务用得到的工具交给模型。

六、相似工具要能区分

两个工具描述接近时，模型会随机选一个：

工具 A：查询订单信息
工具 B：查询订单详情

应该写出它们的差异：「查询订单的状态、金额和物流节点，用于回答订单进度问题」与「查询订单里每件商品的规格和价格，用于回答买了什么的问题」。列表工具和详情工具也一样，写明「列表用来选，详情用来确认；只在准备写入某一项之前调用详情，一次查一个」。

七、怎么验证描述写得好

描述的好坏最终体现在调用行为上，可以从三个地方看：

1. 预览：直接查看真正发给模型的工具 JSON，确认改动已生效、停用的工具不在里面
2. 调用日志：按工具统计调用次数、失败率、参数校验失败次数；
             某个工具从不被调用，或参数总是填错，多半是描述的问题
3. 回归样本：准备一批「应该调 A」「应该调 B」「不该调任何工具」的问题，
             改描述后跑一遍，对比选择正确率

例如 50 条样本里，改描述前某检测工具被错误调用 12 次，补上「不要用它穷举」之后降到 3 次，这种对比才能说明描述改得有效。

八、常见误区与追问

误区：工具描述写一句名字就够了。 模型只能靠描述判断用途和时机，一句名字无法区分相似工具，也说明不了禁止用法。
误区：参数类型对了，模型就会传对值。 Schema 只约束类型，枚举值、格式、来源都要在参数说明里写清。
误区：描述写得越详细越好。 描述每一轮都要发给模型，写成说明文档既费 token 又稀释重点。
误区：描述写了可选，Schema 里是否必填无所谓。 两者不一致时模型会按 Schema 硬塞值，工具按字面匹配就查不到。
误区：只要加调用次数上限，就不用写禁止用法。 上限是兜底，描述里先说清不该怎么用，才能少浪费调用。
追问：怎么知道描述改动生效了？ 预览真正发给模型的工具定义，再看调用日志和回归样本的选择正确率。
追问：工具返回的内容也需要「写给模型看」吗？ 需要，返回里带上下一步提示（如还有更多结果、换条件再查），模型才知道自己看到的是子集。

九、加强记忆

模型只看得到工具名、描述和参数 Schema，它们就是 Prompt 的一部分。描述回答四件事：做什么、什么时候调、什么时候别调、返回怎么读；禁止用法最容易漏，却最能省调用。参数说明写清枚举、格式和来源，ID 写明取自哪个工具的返回。描述和 Schema 必须一致，写了不传表示不限就要声明非必填。描述每轮都发，要准不要长。相似工具写出差异。改完用预览、调用日志和回归样本验证。

项目实战落地

项目里怎么做的

《AI Agent旅游行程智能规划平台》的 8 个工具，描述写在 @Tool 注解里，参数说明写在 @P 注解里，发给模型的就是这两处文字。项目里能看到三种写法：

写清什么时候该调：行程上下文查询工具「编排开始时必须先调用一次」；点位详情工具「只在准备把某个点位写进行程之前调用，一次查一个」；
写清什么时候不该调：行程上下文查询工具「不要重复调用本工具」；距离工具「不要用它穷举搜索最优顺序」；
写清参数取值：班次工具的交通方式「取值：飞机/高铁/动车/大巴」；写入工具的明细类型「取交通/景点/餐饮/住宿/自由活动」；

《AI Agentic RAG高级企业知识库平台》把描述存在 function_tool.description，原样发给模型：新增工具时描述不许为空（「模型靠它判断什么时候调用这个工具」）；管理端能一键查看真正发给模型的工具定义 JSON，改完描述立刻验证；入参说明写错时退化成无参工具，不让整次执行崩掉。

为什么这样取舍

可选参数必须同步声明：写了「不传表示不限」却没写 required = false，参数会进 Schema 的必填列表，模型每次都得硬塞一个值；描述和 Schema 必须说同一件事。
知识库项目把描述放在表里：调描述和调 Prompt 是同一类工作，需要改完马上看效果，不用重新发布。

面试官还会追问

旅游项目在工具中心里改了工具说明，模型下一次看到的描述会跟着变吗？为什么？
距离工具的描述要求「不要用它穷举搜索最优顺序」，那模型应该怎么安排同一天点位的先后顺序？

学完《AI Agent旅游行程智能规划平台》，上面这些追问你都会迎刃而解。

简化版

详细版