工具描述：让Agent听懂工具怎么用

可视化演示

动态演示工具描述的核心机制，通过输入/处理/存储/输出四种模式展示关键概念与交互流程。

一、描述结构四要素

拿到一份新家电的说明书，你最先翻到的一定是“产品功能”那一章：这台机器到底能干什么，适合什么场景。工具描述的第一段也是同理——先告诉 Agent“这个工具是做什么的、什么时候该用它”。比如“查询指定城市实时天气”，而不是“一个天气工具”，后者就像说明书上只写了“一台机器”四个字。

除了功能说明，一份完整的工具描述还包含另外三个层次：参数定义、返回格式、调用示例。这四件事对应 Agent 调用前的四个疑问：这个工具干嘛的？参数怎么传？结果长什么样？具体怎么调用？在 Function Calling（让大模型学会调用外部工具的机制）中，这些内容被组织成一个 JSON 结构，叫做工具 Schema——相当于把说明书整本压缩成一页纸。

就像说明书少了“注意事项”章节会让你踩坑，工具描述缺了任何一个要素，Agent 都会在某个环节卡壳。四要素齐了，这本“说明书”才算合格。

二、参数定义与约束

说明书翻到“按键说明”那一页，每个按钮旁边都得标清楚：这是干什么用的、怎么按、能不能不按、按到什么程度算合适。参数的写法，就是把每个按钮的说明翻译给 Agent 听。

在工具 Schema 里，每个参数都要声明几点：类型是字符串还是数字，是否必填，取值范围有哪些，默认值是什么。比如“温度单位”这个参数，你写“字符串”还不够——Agent 还是会猜“摄氏度”“华氏度”“K”哪个才对；你要写明它只能取 celsius 或 fahrenheit 二选一。这就是给参数画了一个“圈”，把 Agent 的选择限制在合法区域内。

说明书里每个按键都标注清楚，“这是个旋钮，左转减小、右转加大，只能转到 1-5 档”——Agent 照着操作自然不出错。参数约束越明确，Agent 的“误操作”就越少。

三、返回格式规范

家电说明书通常会有一个“指示灯说明”小表格：绿灯常亮表示正常运行，红灯闪烁表示故障，不同故障还有对应编号。工具描述里的返回格式说明，就是给 Agent 的“指示灯说明”。

Agent 调用工具后拿到返回数据，它需要判断：这次调用到底成功没有？数据里哪个字段是温度、哪个是天气？如果失败了，该如何向用户解释、该不该重试？如果描述里只说“返回查询结果”，Agent 面对一团乱麻，只能瞎猜——就像看说明书找不到“红灯闪两下是什么意思”。所以返回结构要写清楚：成功时返回哪些字段、字段类型是什么、失败时错误码和错误信息长什么样。

就像指示灯“一绿一红”让你一眼知道机器状态，清晰的返回格式让 Agent 拿到结果后能果断决定下一步：解析数据、向用户汇报，还是礼貌地道歉重试。模糊的返回说明，等于把 Agent 扔进一个没有指示灯的机房。

四、调用示例编写

说明书里最受欢迎的永远是“快速上手”那一页：三步带你把咖啡拉花做出来。纯文字描述再准确，也不如一个完整例子让人醍醐灌顶。对 Agent 来说，这个“例子”就是调用示例。

调用示例不是摆设，它相当于一种“模仿学习”素材——学术上叫 few-shot（给模型看几个输入输出对，它就能照着规律举一反三）。比如描述“查询天气工具”时附上一个示例：传入 {"city":"北京"}，返回 {"temp":18,"weather":"晴"}。Agent 看了这个例子，就知道了三件事：参数写成什么格式、返回长什么样、字段代表什么含义。示例越贴近真实场景，Agent 学得越快。

图文并茂比通篇理论更让人心安，Agent 也一样。多写几个好例子，胜过在文字描述里反复强调“请一定传对参数”——行动示范比说教管用。

五、常见描述错误

你一定见过这种“翻车说明书”：写着“按任意键继续”，其实只有底部小按钮可用；或者首页印满品牌故事，关键参数却藏在角落里。工具描述里的错误，往往也长这样。

最常见的四种坑，踩中任何一个都会让 Agent 抓狂。第一种是表述模糊——“处理数据”这种话等于没说，处理什么数据、怎么处理、达成什么效果，一概不知，Agent 只能干瞪眼。第二种是参数遗漏——没写类型、没标必填、没给范围，Agent 猜一个传进去，工具当场报错。第三种是过度冗长——把背景故事、实现原理全塞进来，真正关键的信息被淹没，大模型读起来反而抓住了错误重点。第四种是参数幻觉——描述里写的参数，工具后端根本没有实现，Agent 照描述传参，就像说明书承诺“支持语音控制”而机器压根没有麦克风。

一份翻车的说明书会被用户扔进垃圾桶，一份翻车的工具描述则会让 Agent 反复报错、让用户反复重试。写描述时，多问自己一句：“这句话，另一个完全不知情的人能看懂吗？”能，才过关。

六、最佳编写实践

顶级说明书作者有个共同点：他们永远蹲在“第一次用这台机器的人”的视角写，绝不假设读者懂任何背景。给 Agent 写工具描述，请把自己想象成在给一个空白的机器人讲步骤。

基于这个视角，有四条心法值得内化成习惯。第一，站在 Agent 的角度——描述要回答“什么情况下用我”，而不是炫耀“我有多强大”。第二，简明扼要——每句话都有信息量，不写废话，不被冗余淹没重点。第三，持续迭代——工具描述不是一锤子买卖，Agent 在真实场景里调用失误了，就回来打磨措辞，像产品经理迭代文案一样。第四，自动化测试验证——准备一批典型问题，每次改完描述就跑一遍回归，看 Agent 是否都能正确触发工具，用数据说话。

说明书大师不会写完就撒手不管，他会找几个真正的用户试读，看哪里还会按错，然后反复修订。工具描述同样需要“试读”——不过这次的读者是 Agent，而“试读报告”就是那一条条真实调用日志。把描述当成产品来打磨，Agent 才会越用越顺手。

AI 应用场景

Python 演示

import jsonfrom typing import Any, Dict, List REQUIRED_FIELDS = ["name", "description", "parameters"]  def validate_tool_description(schema: Dict[str, Any]) -> List[str]:    """检查工具描述是否包含 Agent 调用所需的必要信息."""    errors = []    for field in REQUIRED_FIELDS:        if field not in schema:            errors.append("缺少必要字段: " + field)    if "parameters" not in schema:        return errors     params_obj = schema["parameters"]    if params_obj.get("type") != "object":        errors.append("parameters.type 应为 object")     props = params_obj.get("properties", {})    required_list = params_obj.get("required", [])    for name, meta in props.items():        if "type" not in meta:            errors.append("参数 [" + name + "] 缺少 type")        if "description" not in meta:            errors.append("参数 [" + name + "] 缺少 description")    for name in required_list:        if name not in props:            errors.append("required 中声明了未定义的参数 [" + name + "]")     if "examples" not in schema or not isinstance(schema["examples"], list):        errors.append("建议提供调用示例 examples, 帮助 Agent 理解用法")    return errors  def print_report(schema: Dict[str, Any]) -> None:    """打印可读的检查报告."""    errors = validate_tool_description(schema)    print("工具: " + schema.get("name", "(未命名)"))    if errors:        for e in errors:            print("  [x] " + e)    else:        print("  [ok] 工具描述合格, Agent 可以放心调用!")  GOOD_SCHEMA = {    "name": "query_weather",    "description": "查询指定城市当前天气状况, 返回温度与天气类型.",    "parameters": {        "type": "object",        "properties": {            "city": {"type": "string", "description": "城市名称, 例如: 北京, 上海."},            "unit": {                "type": "string",                "enum": ["celsius", "fahrenheit"],                "description": "温度单位, 默认 celsius."            }        },        "required": ["city"]    },    "examples": [        {"input": {"city": "北京"}, "output": {"temp": 18, "weather": "晴"}}    ]} BAD_SCHEMA = {    "name": "do_stuff",    "description": "处理数据.",    "parameters": {        "type": "object",        "properties": {            "stuff": {"description": "要处理的东西"}        }    }} if __name__ == "__main__":    print_report(GOOD_SCHEMA)    print_report(BAD_SCHEMA)

1. REQUIRED_FIELDS = [...]定义工具描述必含的首要字段，相当于说明书不能缺封面。
2. for field in REQUIRED_FIELDS:逐一核对必要字段是否都存在。
3. params_obj.get("type") != "object"参数容器必须是 object 类型，否则 Agent 无法按名取参。
4. if "type" not in meta:每个参数都必须有类型标注，缺失则提示。
5. "type": "string", "enum": [...]用枚举约束把参数“圈”进合法范围。
6. if "examples" not in schema缺少调用示例时给出温和提醒，鼓励提供示范。
7. print_report(GOOD_SCHEMA)用合格样例验证检查器输出 “合格”。
8. print_report(BAD_SCHEMA)用模糊描述样例展示如何揪出问题。

常见误区

面试题