工具描述（Tool Description）写得不好会带来哪些问题？如何编写高质量的工具描述？

工具描述低质量带来的问题与高质量编写方法一、工具描述为什么是最关键的字段在整个工具定义中模型能看到的只有三个信息name、description、parameters。其中description 是模型判断要不要用这个工具的首要依据。模型的决策过程: 用户输入: 帮我查一下最近有什么科技新闻 │ ▼ 模型扫描可用工具列表: ┌──────────────────────────────────────────────────┐ │ 工具1: search_web 搜索互联网网页 │ │ 工具2: search_news 搜索新闻 │ │ 工具3: search_database 搜索本地数据库 │ │ 工具4: get_weather 查询天气 │ └──────────────────────────────────────────────────┘ │ │ 模型逐一对比 description 与用户意图 │ ▼ 科技新闻 最匹配 → search_news搜索新闻 如果 description 写得不好这一步就会出错二、低质量描述带来的六大问题问题一工具误选选错工具───────────────────────────────────────────────────── 场景: 有两个搜索类工具 工具A: search_web description: 搜索 ← 太模糊 工具B: search_local_docs description: 搜索 ← 也太模糊 用户: 帮我找一下公司内部的报销制度文档 模型: 两个都叫搜索 → 随机选了 search_web 实际: 应该选 search_local_docs本地文档搜索 结果: 去互联网搜报销制度返回无关网页 ─────────────────────────────────────────────────────根因description 没有区分使用边界模型无法判断该用哪个。问题二过度调用不该调时调了───────────────────────────────────────────────────── 工具: send_email description: 发送邮件 ← 没说适用场景 用户: 帮我写一封给客户的道歉邮件 模型理解: 写邮件 → 涉及邮件 → 调用 send_email 实际: 用户只是想让你帮忙写不是发 结果: 邮件被直接发出去了但用户还没确认内容 ─────────────────────────────────────────────────────根因description 没有说明适用场景模型把提到关键词等同于需要调用。问题三漏调该调时没调───────────────────────────────────────────────────── 工具: calculate_tax description: 计算个人所得税 ← 过于狭窄 用户: 帮我算一下这个项目要交多少增值税 模型理解: 这个工具是算个人所得税的 → 增值税不匹配 → 不调用 实际: 这个工具支持所有税种计算但 description 没写 结果: 模型回答我无法计算增值税实际工具完全可用 ─────────────────────────────────────────────────────根因description 过于狭窄缩小了模型对工具适用范围的理解。问题四参数提取错误───────────────────────────────────────────────────── 工具: create_event description: 创建日历事件 parameters: start_time: description: 开始时间 ← 没说格式 attendees: description: 参与者 ← 没说是邮箱还是姓名 用户: 帮我创建一个明天下午3点的会议邀请张三和李四 模型生成: start_time: 明天下午3点 ← 非标准格式 attendees: [张三, 李四] ← 传了姓名而非邮箱 系统执行: 函数报错——start_time 需要 ISO 8601 格式 ─────────────────────────────────────────────────────根因参数级 description 没有说明格式要求模型用了自然语言格式。问题五多工具场景下的混淆工具越多越严重───────────────────────────────────────────────────── 10个工具description 都很模糊: 工具1: 查询数据 工具2: 搜索信息 工具3: 获取详情 工具4: 检索记录 工具5: 查找内容 ... 用户: 帮我看看昨天有多少新注册用户 模型: 这些工具的 description 几乎一样 → 无法区分 → 随机选一个 → 大概率选错 准确率可能降到 30%-50% ───────────────────────────────────────────────────── 同样10个工具description 写得好: 工具1: 查询用户增长指标返回注册数、活跃数等 工具2: 搜索互联网公开信息返回网页标题和摘要 工具3: 获取订单详情包括商品、金额、状态 工具4: 检索用户行为日志支持按时间筛选 工具5: 全文检索知识库文档返回匹配段落 ... 模型: 新注册用户 → 精确匹配 工具1 准确率可达 90%-98% ─────────────────────────────────────────────────────问题六安全风险───────────────────────────────────────────────────── 工具: delete_file description: 删除文件 ← 没有风险提示和限制说明 用户: 帮我把这些临时文件清理一下 模型: 调用 delete_file(path./temp) 实际: 该函数递归删除可能波及目录下非临时文件 如果 description 写了: 删除指定路径的文件。⚠️ 此操作不可恢复。仅支持删除 /tmp 目录下的文件不支持删除目录。 模型会: 更谨慎地构造参数限制在 /tmp 范围内 ─────────────────────────────────────────────────────三、高质量描述的编写框架3.1 五要素模型一个生产级的工具 description 应包含以下五个要素┌──────────────────────────────────────────────────────┐ │ │ │ ① 功能说明 — 这个工具做什么 │ │ ② 适用场景 — 什么情况下该用 │ │ ③ 排除场景 — 什么情况下不该用 │ │ ④ 输出概要 — 返回什么 │ │ ⑤ 限制与注意 — 有哪些约束条件 │ │ │ └──────────────────────────────────────────────────────┘3.2 逐要素详解① 功能说明写法一句话说清这个工具能做什么动作作用在什么对象上。公式: [动词] [操作对象] [核心能力] ✅ 查询指定城市的实时天气信息 动词: 查询 对象: 指定城市的实时天气 能力: 获取信息 ✅ 从业务数据库中查询结构化数据并返回汇总统计结果 动词: 查询 对象: 业务数据库中的结构化数据 能力: 查询汇总 ❌ 天气功能 ← 不是句子没有动作 ❌ 获取数据 ← 过于宽泛什么数据 ❌ 这个工具可以用来查询天气相关信息等 ← 相关信息等是模糊表述② 适用场景写法列举 2-3 种典型的用户意图模式。✅ 适用于用户询问某地当前天气、需要获取温度或天气状况的场景 ✅ 适用于 - 查询特定商品的库存数量 - 按条件筛选库存列表 - 检查某商品是否缺货 ❌ 适用于天气场景 ← 太笼统 ❌ 适用于需要天气信息时 ← 循环定义③ 排除场景写法明确指出虽然看起来相关但不该用这个工具的情况。✅ 不适用于查询未来几天的天气预报请使用 get_forecast → 指向替代工具帮模型做正确选择 ✅ 不适用于查询历史天气数据请使用 get_weather_history ✅ 不适用于数学计算请使用 calculate 工具 也不适用于本地文档搜索请使用 search_docs 工具 ❌ 不写排除场景 ← 模型可能在边界情况下误调 ❌ 不适用于其他用途 ← 其他是什么没有信息量④ 输出概要写法简述返回的数据结构帮模型理解拿到结果后怎么用。✅ 返回JSON格式包含字段temp(温度)、condition(天气状况)、 wind(风速风向)、humidity(湿度) ✅ 返回航班列表每个航班包含航班号、价格、起飞时间、 到达时间。最多返回20条。 ❌ 返回结果 ← 没说返回什么 ❌ 返回天气数据 ← 什么数据结构是什么⑤ 限制与注意写法频率限制、权限要求、风险提示等。✅ 每次调用消耗1次API配额每日上限100次 ✅ 此操作不可撤销调用前应确认用户意图 ✅ 仅支持查询最近90天内的数据更早的数据请联系管理员 ✅ 收件人数量不超过10个超出将报错3.3 完整示例五要素组装工具: search_flights description: 搜索航班信息并返回可用航班列表包括航班号、价格、 起飞时间、到达时间和舱位等级。 〔①功能说明 ④输出概要〕 适用于用户查询机票价格、比较航班、查找特定航线 可用航班的场景。 〔②适用场景〕 不适用于预订机票请使用 book_flight或查询 已有订单状态请使用 get_order_status。 〔③排除场景〕 单次查询最多返回20条结果仅支持查询未来30天 内的航班。日期参数需使用YYYY-MM-DD格式。 〔⑤限制与注意〕四、参数级描述的编写方法工具级 description 决定选不选参数级 description 决定怎么填。4.1 参数描述的四要素┌──────────────────────────────────────────────┐ │ │ │ ① 含义 — 这个参数代表什么 │ │ ② 格式 — 值应该是什么形式 │ │ ③ 示例 — 给一个具体例子 │ │ ④ 约束 — 有什么限制条件 │ │ │ └──────────────────────────────────────────────┘4.2 逐类示例// ──────────── 字符串类型 ────────────// ❌ 差city:{type:string,description:城市}// ✅ 好city:{type:string,description:城市名称使用中文全称如北京市、上海市、广州市// ↑含义 ↑格式 ↑示例}// ──────────── 日期时间类型 ────────────// ❌ 差start_date:{type:string,description:开始日期}// ✅ 好start_date:{type:string,format:date,description:查询开始日期格式 YYYY-MM-DD如 2026-09-01。仅支持查询最近90天内的日期。// ↑含义 ↑格式 ↑示例 ↑约束}// ──────────── 枚举类型 ────────────// ❌ 差region:{type:string,enum:[north,south,east,west],description:地区}// ✅ 好region:{type:string,enum:[north,south,east,west],description:地区筛选north华北south华南east华东west华西。不传则默认查询全国。// ↑含义 ↑每个枚举值的语义 ↑默认行为}// ──────────── 数组类型 ────────────// ❌ 差tags:{type:array,items:{type:string},description:标签}// ✅ 好tags:{type:array,items:{type:string},description:筛选标签列表每个标签为字符串。多个标签之间为AND关系需同时满足。如 [urgent, bug]。最多5个标签。// ↑含义 ↑元素说明 ↑逻辑关系 ↑示例 ↑约束}// ──────────── 数值类型 ────────────// ❌ 差limit:{type:integer,description:数量}// ✅ 好limit:{type:integer,minimum:1,maximum:1000,description:返回结果的最大条数默认100最大1000。值越大响应越慢。// ↑含义 ↑默认值 ↑约束 ↑注意事项}4.3 参数描述的陷阱词清单这些词没有信息量模型无法据此正确填参数❌ 相关数据 → 什么数据相关是什么意思 ❌ 必要信息 → 哪些信息是必要的 ❌ 适当值 → 什么范围算适当 ❌ 可选参数 → 可选但没说默认行为是什么 ❌ 其他 → 其他包括什么 ❌ 等 → 等后面还有什么 ❌ 详见文档 → 模型看不到你的文档 ❌ 同上 → 模型不会关联上下文五、多工具场景下的描述设计5.1 描述差异化原则当工具数量超过 5 个时description 之间的区分度比单个 description 的质量更重要。关键规则: 相似工具的 description 必须有明确的区分信号词 一组相似工具的描述设计: 工具A: search_web 搜索互联网公开网页内容返回网页标题、摘要和链接。 适用于查找公开资讯、技术文档、百科知识。 不适用于搜索公司内部文档或本地数据。 区分信号: 互联网 公开 网页 工具B: search_internal_docs 搜索公司内部文档库包括制度文件、项目文档、 会议纪要。适用于查找公司内部资料。 不适用于搜索互联网公开信息。 区分信号: 公司内部 文档库 制度文件 工具C: search_chat_history 搜索当前用户的历史对话记录返回之前的问答内容。 适用于查找之前讨论过的话题或结论。 不适用于搜索文档或网页。 区分信号: 历史对话 之前讨论 工具D: search_database 从业务数据库中查询结构化数据支持按条件筛选 和聚合统计。适用于查询业务指标、统计数据。 不适用于全文搜索或文档检索。 区分信号: 业务数据库 结构化数据 统计5.2 区分信号词设计策略: 在 description 开头就给出身份标签 搜索互联网网页... → 身份标签: 互联网 查询业务数据库... → 身份标签: 数据库 检索知识库文档... → 身份标签: 知识库 搜索历史对话... → 身份标签: 历史对话 模型在匹配时首先抓身份标签做粗筛再做精细匹配5.3 工具数量与准确率的关系工具选择准确率 100% ┤ │ ● description 写得好的情况 95% ┤ ● ● │ ● ● 90% ┤ ● ● │ 85% ┤ ● │ ● description 写得差的情况 80% ┤ ● │ 75% ┤ │ ● 70% ┤ ● └──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──→ 工具数量 1 3 5 8 10 15 20 30 50 100 关键结论: - 10个工具以内: 好描述和差描述差距约 5-10% - 20个工具: 差距扩大到 15-25% - 50个工具: 差距可达 30% - 100个工具: 差描述几乎不可用六、高质量描述的对照案例库案例一查询类工具─────────── 差 ─────────── name: query, description: 查询数据 问题: 查什么数据什么场景用怎么查全不知道。 ─────────── 好 ─────────── name: query_sales_data, description: 从销售数据库中查询销售数据支持按时间范围、 地区、产品类别筛选返回销售额、订单数、客单价等汇总指标。 适用于生成销售报表、分析销售趋势、查看区域业绩。 不适用于查询库存数据请使用 query_inventory或 客户信息请使用 get_customer。 单次查询时间跨度不超过12个月超出请分次查询。案例二操作类工具─────────── 差 ─────────── name: update, description: 更新记录 问题: 更新什么什么条件才能更新有什么风险 ─────────── 好 ─────────── name: update_order_status, description: 更新指定订单的状态。仅支持在以下状态间转换: 待付款→已付款、已付款→已发货、已发货→已完成。 不支持回退状态如已完成→已发货。 此操作不可撤销调用前需确认用户已知晓状态变更。 适用于订单履约流程中的状态推进。 如果需要修改订单内容如商品、收货地址请使用 update_order_detail。案例三通知类工具─────────── 差 ─────────── name: notify, description: 发送通知 问题: 通知谁什么渠道什么场景 ─────────── 好 ─────────── name: send_sms_notification, description: 向指定手机号发送短信通知。 适用于订单状态变更通知、验证码发送、预约提醒等场景。 不适用于营销推广短信受法律限制需使用 send_marketing_sms 并确认用户已同意接收。 单条短信正文不超过70个字符含签名超出将自动拆分 为多条计费。发送频率限制同一手机号每分钟最多1条、 每小时最多5条。案例四分析类工具─────────── 差 ─────────── name: analyze, description: 分析数据 问题: 分析什么怎么分析返回什么 ─────────── 好 ─────────── name: analyze_sentiment, description: 对给定文本进行情感分析返回正面、负面、 中性三种情感标签及各自的置信度分数0-1。 适用于分析用户评论、客服对话、社交媒体内容的 情感倾向。 不适用于多语言文本仅支持中文和英文或 长度超过5000字的文本请先截断或分段。 单次分析耗时约1-3秒。七、描述编写检查清单7.1 工具级描述检查□ 是否说明了工具做什么功能 □ 是否说明了什么情况下用适用场景 □ 是否说明了什么情况下不用排除场景 □ 是否指出了替代工具如有 □ 是否说明了返回什么输出概要 □ 是否标注了重要限制条件 □ 是否与相似工具有明确区分 □ 长度是否在 30-150 词之间过短信息不足过长注意力分散 □ 是否避免了等相关其他等模糊词7.2 参数级描述检查□ 是否说明了参数含义 □ 是否说明了值格式含示例 □ 是否说明了默认值如为可选参数 □ 是否说明了取值范围或枚举语义 □ 是否说明了与其他参数的依赖关系如有 □ 是否说明了单位如为数值类型 □ 是否避免了适当值必要信息等陷阱词7.3 整体一致性检查□ name 与 description 是否语义一致 □ description 与 parameters 是否对应没有描述中提到 的参数在 schema 中缺失 □ required 中的参数是否都有 description □ 有 enum 的参数是否在 description 中解释了每个值 □ 相似工具的 description 是否有区分度一句话总结工具描述是模型选择工具的唯一决策依据——写得差会导致误选、漏选、过度调用、参数错误工具越多问题越严重。高质量描述的核心是五要素齐全功能适用场景排除场景输出概要限制注意相似工具之间必须有明确的区分信号词参数级描述必须包含含义、格式、示例和约束。检验标准很简单把你的 description 拿给一个不了解这个工具的人看他能否准确判断什么情况下该用、什么参数怎么填如果能模型大概率也能。