怎么给 Qwen 写工具描述
工具使用属 Qwen 系列能力面,qwen3.7-max 接口未记载 tools 参数;工具描述按「名称、参数与类型、返回值、失败回退」四件套备好,缺项可以先让模型评审出来——不用等接入后才暴露。
一、前提与适用
| 前提 | 说明 |
|---|---|
| 适用模型 | 支持 tools 参数的 Qwen 系列模型档位(按各档接口文档核对) |
| 能力面依据 | 官方能力清单中工具使用属 Qwen 系列能力;qwen3.7-max 接口文档未记该参数 |
| 本节做法 | 四件套写清工具描述;用纯文本评审让模型找出缺项 |
| 不适用 | 已经有成熟 function calling 框架的工程——schema 由框架校验,本节写法作描述文档参考 |
二、怎么做
工具描述四件套,每件都要可执行:
- 名称:一个动词短语,范围与功能一一对应(
query_weather管「查」,不管「订阅」)。 - 参数与类型:每个参数带类型、必填与否、取值约束——「city(城市名)」缺类型,模型不知道该传字符串还是行政区划代码。
- 返回值:结构说清(字段列表或示例 JSON),「返回:天气信息」这种一句话描述会让调用方无从解析。
- 失败回退:超时、无结果、参数非法时返回什么——没写回退,模型面对报错只能瞎猜或编造。
坏写法:
工具:query_weather,查询城市天气,参数是城市名,返回天气信息。
四件套缺了两件半:参数无类型、返回值无结构、失败回退完全没有。
改写后的完整提示词(评审形态——让模型当接口评审员):
你是接口评审员。下面是一份给模型用的工具描述,请对照「名称、参数与类型、返回值、失败回退」四项检查,输出缺失项清单,每项一行,格式:缺失:<项>:<建议补充内容>。没有缺失则输出「无」。
工具描述:
名称:query_weather
用途:查询城市天气
参数:city(城市名)
返回:天气信息
评审形态的价值:四件套检查项写进提示词,模型按清单逐项过,缺什么报什么。
「描述是否过四项检查」可以做成可跑检查:
## EXPECT: 名称=1 参数类型=0 返回结构=0 失败回退=0
DESC = """名称:query_weather
用途:查询城市天气
参数:city(城市名)
返回:天气信息"""
import re
name = int("名称:" in DESC)
ptype = int(bool(re.search(r"(str|int|float|bool|字符串|整数|布尔)", DESC)))
ret_struct = int(bool(re.search(r"返回.*(:|\{|字段)", DESC)))
fallback = int(("失败" in DESC) or ("超时" in DESC) or ("回退" in DESC))
print(f"名称={name} 参数类型={ptype} 返回结构={ret_struct} 失败回退={fallback}")
实测输出与判定:脚本实跑输出与首行注释一致。逐条判定:坏描述只有「名称」一项达标,参数类型、返回结构、失败回退三项计 0——与判定器预期完全一致。生产中把 DESC 换成真实工具描述即可复用;缺项内容则由下面的实测输出评审给出。
怎么看这个示例:判定器是本地脚本,上面那条提示词另在 qwen3.7-max(temperature=0.7、top_p=0.8) 上实测;脚本输出不等于模型输出,两者分别核对。
模型回复(真实输出节选):
缺失:参数与类型:建议补充参数的数据类型(如 string)以及是否为必填项。
缺失:返回值:建议补充返回值的具体数据类型和字段结构(如包含温度、湿度、天气状况的 JSON 对象)。
缺失:失败回退:建议补充查询失败、城市不存在或网络异常时的错误处理机制、错误码或默认提示信息。

以上为模型真实回复的节选,实测日期 2026-11-16。
三、参数与边界
| 边界 | 说明 |
|---|---|
| 接口边界 | qwen3.7-max 接口文档未记 tools 参数;写法按系列能力面口径准备,接入前核对目标档位文档 |
| 评审局限 | 模型评审只能查描述文本的自洽性,参数取值是否合理仍需业务方确认 |
| schema 严格性 | 接入 function calling 后以框架的 JSON Schema 校验为准,本节四件套是描述底稿 |
| 描述漂移 | 工具升级后描述要同步改,过时描述会诱导模型传错参数 |
四、验收清单
| 检查项 | 通过标准 |
|---|---|
| 四件套齐 | 名称、参数类型、返回结构、失败回退四项逐项在案(判定器可查) |
| 评审闭环 | 模型评审报出的缺项全部补齐,复审输出「无」 |
| 边界可回挂 | 每个参数的取值约束写进描述,不靠约定俗成 |
| 停手条件 | 接入后模型仍传错参数,先核对描述与实际接口是否漂移 |
五、注意与相关
工具描述是写给「选择工具的那个环节」看的说明书,不是给人看的简介——可执行是底线:每个参数能照着传值,每种失败能照着回退。qwen3.7-max 上用评审形态先把描述打磨好,接入支持 tools 的模型档位时直接以四件套底稿生成 schema。评审输出的缺项清单本质上就是 5.3 的自检清单反着用;工具调用失败后的多轮重试口径见 大需求怎么拆成 Qwen 多轮对话。