我的 AI Agent 老是选错工具、参数也填得乱七八糟,我一度怀疑是模型不行,排查才发现是我给工具写的描述太含糊、模型根本"看不懂"该怎么用,我对着工具描述是模型理解工具的唯一窗口这个坑排查了大半天的复盘

这是我做"能调用工具的 AI Agent"时,栽的一个关于"怎么把工具'教'给模型"的跟头。它让我明白:Agent 能不能用对工具,不只取决于模型有多聪明,更取决于你有没有把工具"说明白"——而我一开始,完全低估了"给工具写好描述"这件事的重要性。

需求是做一个能调用多个工具的 Agent。我给它配了几个工具,但工具的描述(name/description/参数说明)写得很随意:

# 给Agent配置的工具(描述写得含糊的版本)
TOOLS = [
    {
        "name": "search",                    # 名字太泛
        "description": "搜索",               # ★ 描述只有俩字! 搜什么? 数据库还是网络?
        "parameters": {"q": {"type": "string"}}   # 参数叫q, 没说是什么
    },
    {
        "name": "query",                     # 和search有什么区别? 模型分不清
        "description": "查询数据",            # ★ 含糊! 查什么数据? 和search啥区别?
        "parameters": {"input": {"type": "string"}}   # input是什么? 没说
    },
    # ... 还有几个描述同样含糊的工具
]

# 结果: Agent 表现飘忽不定——
#   - 该用 query(查数据库)时, 它却调了 search;
#   - 调用工具时, 参数填得乱七八糟(因为不知道参数啥意思);
#   - 有时面对几个相似的工具, 干脆"选择困难"、乱选一个。

我一开始以为是"模型不够聪明",换了更强的模型,问题依旧。直到我站在模型的视角重新看这些工具描述,才恍然大悟:"搜索""查询数据"——就这么含糊的几个字,参数叫 q、input 也没任何说明,换成我是个新来的人,看到这样的"工具说明书",我也根本不知道该用哪个、参数该填什么啊!模型不是"不聪明",而是我根本没把工具说清楚——它看到的,就是这么一份含糊不清的说明书,自然就用错了。

第一件事:看清真相——工具的描述,是模型理解和使用工具的唯一窗口

我去深入理解了 Agent 是如何选择和调用工具的,才彻底明白这个"模型用错工具"的根源——Agent 在决定"用哪个工具、怎么填参数"时,它唯一能依据的,就是你提供的工具的 name、description、参数 schema 这些信息;模型看不到工具的实现代码,它只能靠这些"自然语言+结构"的描述,去理解"这个工具是干什么的、什么时候该用、参数是什么意思";所以,工具的描述写得好不好,直接决定了模型能不能用对它——描述就是模型的"工具说明书"。

工具描述对Agent的重要性的真相

# 1. Agent 是怎么"用工具"的?
#    - 你把一组工具的 [name + description + 参数schema] 提供给模型;
#    - 模型根据【用户的需求】和【这些工具的描述】, 决定:
#      a) 选哪个工具(理解每个工具"是干什么的、什么时候该用");
#      b) 怎么填参数(理解每个参数"是什么含义、什么格式");
#    - 然后模型生成一个"工具调用"(工具名+参数), 你的代码去执行。

# 2. ★ 关键: 模型【看不到工具的实现代码】!
#    - 它对一个工具的全部认知, 100% 来自你写的那段 name/description/schema;
#    - 这段描述, 就是模型理解和使用这个工具的【唯一窗口/说明书】。

# 3. 所以描述写得差, 模型就用不好:
#    - description含糊("搜索""查询数据") → 模型不知道这工具具体干啥、何时用 → 选错;
#    - 多个工具描述相似/职责重叠 → 模型分不清该用哪个 → 乱选;
#    - 参数没说明(q, input) → 模型不知道参数啥意思、啥格式 → 填错;
#    - 缺少使用场景/示例 → 模型靠猜 → 用法不对。

# 4. 类比: 这就像你给一个【很聪明但对你的系统一无所知的新人】,
#    递一份"工具操作手册"让他干活;
#    - 手册写得清楚(每个工具干啥、何时用、参数含义、给例子)→ 他能干得很好;
#    - 手册写得含糊("搜索"俩字) → 再聪明的新人也会用错、问东问西、瞎试。
#    - 模型就是这个"聪明的新人", 描述就是那份手册。

# 5. 所以: "为工具写好描述", 是一种【面向模型的"提示词工程"】——
#    它和"写好给模型的prompt"一样重要, 是Agent能力的关键部分, 不是可有可无的注释。

# 核心: 模型看不到工具实现, 它选工具/填参数全靠工具的name/description/schema(唯一窗口);
#   描述含糊/重叠/参数不清, 模型就会选错工具、填错参数; 写好工具描述是Agent的核心提示词工程。

真相大白,我幡然醒悟。原来 Agent 在决定"用哪个工具、怎么填参数"时,唯一能依据的,就是你提供的工具的 name、description、参数 schema;模型看不到工具的实现代码,它对一个工具的全部认知,100% 来自你写的那段描述——这段描述就是模型理解和使用这个工具的唯一窗口。所以描述写得差,模型就用不好:description 含糊("搜索""查询数据")→ 模型不知道工具具体干啥、何时用 → 选错;多个工具描述相似/职责重叠 → 分不清该用哪个 → 乱选;参数没说明(q、input)→ 不知道参数含义格式 → 填错;缺少场景/示例 → 靠猜 → 用法不对。打个比方:这就像你给一个"很聪明但对你的系统一无所知的新人",递一份"工具操作手册"让他干活——手册写得清楚(每个工具干啥、何时用、参数含义、给例子),他能干得很好;手册写得含糊("搜索"俩字),再聪明的新人也会用错、瞎试。模型就是这个聪明的新人,描述就是那份手册。所以:"为工具写好描述",是一种面向模型的"提示词工程"——它和"写好给模型的 prompt"一样重要,是 Agent 能力的关键部分,绝不是可有可无的注释。

第二件事:正解——把工具描述当"给模型的说明书"认真写,职责单一、参数清晰、给示例

搞懂了原理,正解就清晰了:像写给新人的说明书一样认真写工具描述——清楚说明"用途、何时用、何时不用",参数 schema 精确(类型/枚举/约束/含义),工具职责单一不重叠,必要时给使用示例。

# ====== 正解: 清晰、明确、面向模型的工具描述 ======
TOOLS = [
    {
        "name": "search_products",          # ★ 名字具体, 一看就知道搜什么
        "description": (                     # ★ 描述详尽: 用途+何时用+何时不用
            "在商品数据库中按关键词搜索商品, 返回匹配的商品列表(含名称、价格、库存)。"
            "当用户想查找、浏览、比较商品时使用。"
            "注意: 此工具只搜商品, 不要用它搜订单或用户(那些用对应的工具)。"
        ),
        "parameters": {
            "keyword": {                     # ★ 参数名有意义
                "type": "string",
                "description": "搜索关键词, 如商品名称或类别, 例: '蓝牙耳机'"  # ★ 说明+示例
            },
            "max_price": {
                "type": "number",
                "description": "(可选)价格上限, 只返回不超过此价格的商品"
            }
        }
    },
    {
        "name": "get_order_status",          # 职责单一: 专门查订单状态
        "description": "根据订单号查询订单的当前状态(待付款/已发货/已完成等)。当用户询问某个订单进展时使用。",
        "parameters": {
            "order_id": {"type": "string", "description": "订单号, 如 'ORD12345'"}
        }
    },
    # 每个工具职责单一、描述清晰、参数有说明和示例, 模型一看就知道选哪个、怎么填。
]

# ====== 写好工具描述的几个要点 ======
# 1. name 要具体: search_products 好过 search; 一眼看出它干什么、作用对象。
# 2. description 要说清: 用途 + "什么时候用" + (必要时)"什么时候不要用"。
# 3. 职责单一、避免重叠: 别让两个工具功能含糊重叠, 让模型难抉择; 一个工具干一件清楚的事。
# 4. 参数 schema 要精确: 类型、是否必填、枚举值(限定取值)、约束、含义说明、示例。
#    - 能用枚举就用枚举(如 status: enum["paid","shipped"]), 限定模型只能填合法值。
# 5. 给示例: 在description或参数说明里给典型用法/取值示例, 模型更容易学对。
# 6. 站在模型视角自检: "如果我是个不懂这系统的人, 看这描述, 知道何时用、怎么填吗?"

# ====== 配合: 工具数量别太多、别太碎 ======
# 工具太多/太碎, 模型选择负担大、容易选错。→ 工具集要精简、职责清晰。

# 核心: 把工具描述当"给模型的说明书"认真写——name具体、description说清用途和时机、职责单一不重叠、
#   参数schema精确(类型/枚举/含义/示例); 站在模型视角自检"看得懂吗"; 工具集精简不冗余。

修复的核心,是"把工具描述当给模型的说明书认真写"。写好工具描述的几个要点:一、name 要具体(search_products 好过 search,一眼看出干什么、作用对象);二、description 要说清(用途 + "什么时候用" + 必要时"什么时候不要用");三、职责单一、避免重叠(别让两个工具功能含糊重叠让模型难抉择,一个工具干一件清楚的事);四、参数 schema 要精确(类型、是否必填、枚举值、约束、含义说明、示例——能用枚举就用枚举限定模型只能填合法值);五、给示例(在描述或参数说明里给典型用法/取值示例);六、站在模型视角自检("如果我是个不懂这系统的人,看这描述,知道何时用、怎么填吗?")。还要配合:工具数量别太多/太碎(模型选择负担大、容易选错,工具集要精简、职责清晰)。归根结底:把工具描述当"给模型的说明书"认真写——name 具体、description 说清用途和时机、职责单一不重叠、参数 schema 精确(类型/枚举/含义/示例);站在模型视角自检"看得懂吗";工具集精简不冗余。

第三件事:Agent 工具设计相关的其他常见坑

排查后我把 Agent 工具设计相关的其他常见坑也系统梳理了一遍。

Agent 工具设计的其他常见坑

# 1. 工具描述含糊(本文): 模型选错/填错。→ 清晰描述+精确schema+示例。

# 2. 工具太多太碎: 选择负担大、易选错。→ 精简工具集、合并琐碎工具。

# 3. 工具职责重叠: 多个功能相似的工具, 模型难抉择。→ 职责单一不重叠。

# 4. 工具返回结果对模型不友好: 返回一大坨原始数据/难懂的格式, 模型难理解利用。
#    → 返回结构化、简洁、模型易懂的结果(必要时摘要)。

# 5. 参数没用枚举/约束限定: 能枚举的不枚举, 模型可能填非法值。→ schema里用枚举/约束。

# 6. 工具报错信息对模型没用: 报错只说"失败", 模型不知怎么改。→ 错误信息要能指导模型修正。

# 7. 工具有危险副作用却没在描述里警示: 模型可能轻率调用删除等危险操作。→ 描述里强调/加确认。

# 8. 不用模型/框架的标准tool-calling: 自己用prompt硬解析工具调用, 不稳定。→ 用function calling。

# 共同根源: Agent调用工具, 本质是"模型(靠描述理解工具)和你的代码(执行工具)之间的协作";
#   这个协作的质量, 取决于"工具对模型的可理解性"(描述)和"工具结果对模型的可用性"(返回)。

# 核心: 工具设计要面向模型——描述清晰、职责单一、参数有约束、返回对模型友好、错误能指导修正;
#   工具集精简; 把"给模型设计好用的工具"当成Agent工程的核心能力, 像设计好的API一样设计工具。

排查让我把 Agent 工具设计的其他坑也梳理清了。一、工具描述含糊(本文)。二、工具太多太碎(选择负担大,精简工具集)。三、工具职责重叠(职责单一不重叠)。四、工具返回结果对模型不友好(返回结构化简洁的结果、必要时摘要)。五、参数没用枚举/约束(能枚举就枚举限定合法值)。六、工具报错信息对模型没用(错误信息要能指导模型修正)。七、危险副作用没在描述里警示。八、不用标准 function calling(自己 prompt 硬解析不稳定)。它们的共同根源是:Agent 调用工具,本质是"模型(靠描述理解工具)和你的代码(执行工具)之间的协作";这个协作的质量,取决于"工具对模型的可理解性(描述)"和"工具结果对模型的可用性(返回)"。核心是:工具设计要面向模型——描述清晰、职责单一、参数有约束、返回对模型友好、错误能指导修正;工具集精简;像设计好的 API 一样设计工具。下面这张图,是这次工具描述含糊的成因与解法:

第四件事:好工具描述 vs 坏工具描述对照表

这次踩坑后,我把"坏的工具描述"和"好的工具描述"对照整理成一张表。

这张表把好坏工具描述钉清了。核心是:好的工具描述,处处体现着"为模型(读者)着想"——名字具体、用途说清、职责单一、参数有意义且有说明示例、取值有约束、返回对模型友好;坏描述则处处含糊、让模型靠猜。它给我的最大启发是:"为工具写描述",和"为别人写 API 文档/接口契约",本质是同一件事——你都是在向一个"不了解内部实现、只能依据你的描述来使用它"的使用者,清晰地传达"这是什么、怎么用、有什么约束";区别只是这个使用者从"人类开发者"变成了"大模型"。这让我意识到一个有趣的延伸:随着 AI Agent 时代到来,"把东西向 AI 解释清楚"正在成为一项新的、重要的工程能力——写好给模型的工具描述、给模型的 prompt、给模型的上下文,本质都是"面向 AI 的清晰沟通";而它和"面向人类的清晰沟通"(写好文档、命名、注释)遵循着相通的原则:站在对方(读者/模型)的角度,清楚、准确、无歧义地表达。把"给模型写好工具描述"当成"面向 AI 的接口文档"来认真对待、用"清晰沟通"的通用原则去写——是 AI Agent 时代的一项核心新能力。

第五件事:Agent 的能力 = 模型 + 工具 + 描述

这次让我重新理解了"一个 Agent 强不强"到底由什么决定。

这张表道出了 Agent 能力的"构成"。核心是:一个 Agent 强不强,不只取决于底层模型有多强,而是模型能力、工具能力、工具描述、提示词上下文、编排逻辑共同决定的;其中"工具描述"是最容易被忽略、却极其关键的一环——它直接决定了"模型能不能把工具的能力发挥出来"。它给我的深刻启发是:在 AI 应用里,有一种常见的误区——把效果不好一股脑归咎于"模型不够强",然后一味地等更强的模型、或换更贵的模型;但很多时候,真正的瓶颈不在模型,而在我们围绕模型做的工程(工具怎么设计、描述怎么写、上下文怎么给、流程怎么编排)——这些"模型周边的工程",对最终效果的影响,常常和模型本身一样大,甚至更大、更可控。这让我对做 AI 应用有了更务实的认识:与其被动地等"更强的模型"来拯救效果,不如主动地把"模型周边的工程"做扎实——把工具设计好、描述写清楚、上下文组织好、流程编排稳健;"用好的工程,把现有模型的能力充分发挥出来",往往比"苦等下一代模型"更现实、更可控、收益更大。认清 Agent 能力是"模型+工具+描述+工程"的合力、把发力点放在可控的工程上而非只怪模型——是这个工具描述坑,带给我的关于"如何做好 AI 应用"的更宏观认知。

第六件事:给 Agent 设计工具时,我现在的判断习惯

现在每当我给 Agent 设计/添加一个工具,我都会按这张图先想清楚:

这张图的精髓,是"工具要面向模型设计:name 具体、描述说清、职责单一、参数清晰、返回友好、自检看得懂"。name 具体、description 说清用途和时机、和已有工具不重叠、参数有意义有说明示例和枚举约束、返回结构化易懂、错误能指导修正;站在模型视角自检"看得懂吗",工具集别太多太碎。这套习惯,让我设计工具时,从"随手写个名字和俩字描述"变成了"像写 API 文档一样面向模型认真设计"——核心始终是:模型靠工具描述理解工具,描述是唯一窗口;描述清晰、职责单一、参数精确,模型才能用对。

我立下的几条规矩

这场"Agent 选错工具填错参数"的事故,换来了我做 AI Agent 时,刻进骨子里的几条铁律:

1. 模型看不到工具实现,只靠描述理解工具。描述是模型的唯一窗口。
2. 工具描述是面向模型的提示词工程。不是可有可无的注释。
3. name 具体、description 说清用途和时机。含糊的描述模型用不好。
4. 工具职责单一、不重叠。别让模型在相似工具间难抉择。
5. 参数 schema 精确:含义+示例+枚举约束。能枚举就枚举限定合法值。
6. 返回对模型友好、错误能指导修正。工具集精简别太碎。
7. 站在模型视角自检"看得懂吗"。像给新人写说明书一样。

附:一个面向模型设计良好的工具定义模板

这次踩坑后,我把"一个面向模型设计良好的工具"该有的要素,沉淀成了一个模板(以 OpenAI function calling 风格的 schema 示意),新工具都照着它写:

# ====== 面向模型的工具定义模板 ======
tool = {
    "type": "function",
    "function": {
        # 1. name: 动词+宾语, 具体明确, 一看知道干什么
        "name": "create_refund",
        # 2. description: 用途 + 何时用 + 何时不用 + (可选)注意事项
        "description": (
            "为指定订单创建退款。"
            "当用户明确要求退款、且订单状态允许退款时使用。"
            "不要用于查询退款状态(那用 get_refund_status)。"
            "注意: 这是会扣减商家资金的操作。"
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "order_id": {
                    "type": "string",
                    "description": "要退款的订单号, 格式如 'ORD-12345'"   # 含义+格式
                },
                "amount": {
                    "type": "number",
                    "description": "退款金额(元), 必须大于0且不超过订单实付金额"  # 约束说明
                },
                "reason": {
                    "type": "string",
                    "enum": ["quality", "wrong_item", "no_longer_needed", "other"],  # 枚举限定
                    "description": "退款原因, 从给定选项中选择"
                }
            },
            "required": ["order_id", "amount", "reason"]   # 明确哪些必填
        }
    }
}

# ====== 这个模板体现的要点(逐条对照) ======
# - name: create_refund(动词+宾语, 具体)
# - description: 说清"是什么(为订单退款)+何时用(用户要退款且状态允许)+何时不用(查状态用别的)+注意(扣商家钱)"
# - 每个参数都有: 明确的类型 + 含义说明 + 格式/约束 + (能枚举的)枚举限定 + required标明必填
# - 危险操作(扣钱)在description里明确警示, 提醒上层加确认

# 核心: 一个好的工具定义 = 具体的name + 说清用途/时机/注意的description + 每个参数都有类型/含义/
#   约束/枚举/必填标注; 像写一份给模型看的、清晰无歧义的"接口契约"; 危险操作要警示。

这个工具定义模板,是我这次踩坑后最实用的沉淀。它把"一个面向模型设计良好的工具"该有的所有要素,凝结成了一个可照抄的范本:具体的 name(动词+宾语)、说清"是什么+何时用+何时不用+注意事项"的 description、每个参数都标注类型/含义/格式约束/枚举/是否必填、危险操作在描述里明确警示。对比我最初那个"名字叫 search、描述只有'搜索'俩字、参数叫 q"的工具,这个模板的每一处,都在主动地、周到地为"读这份定义的模型"扫清理解障碍。这正是我想用这个模板传达的核心思想:设计一个"给模型用的工具",和设计一个"给开发者用的好 API",其精髓是相通的——清晰的命名、完备的文档、明确的参数契约、对危险操作的警示;无论使用者是人还是 AI,"一个好的接口,应该让使用者无需了解内部实现,仅凭接口本身就能正确、安全地使用它"这个原则,都是一样的。而把这套要素固化成模板,价值在于:它让"把工具设计好"这件需要经验和细心的事,变成了"照着模板逐条填空、就不会漏掉关键要素"的、可复制的标准动作;它把"设计好工具描述"的最佳实践,从"靠每个人自觉做好",变成了"有个范本兜底、人人都能做到及格线以上"。把"面向模型的好工具设计"沉淀成一个可照抄的模板、用工程化的方式保证工具质量——这,是我用一次工具描述含糊的事故,换来的、关于"如何系统性地为 Agent 设计好工具"的实用智慧。

写在最后

回头看,这场由"工具描述含糊"引发的、Agent 用错工具的事故,真正教给我的,远不止"把描述写清楚"这一个技巧。它让我对"与 AI 协作,本质是一种'沟通'",有了一次全新的认识。我栽跟头,是因为我一开始把 Agent 用错工具,归咎于"模型笨",而完全没想到问题出在"我没把话说清楚"。我潜意识里以为,模型既然这么"聪明",就应该能自己搞懂我那含糊的工具是干什么的——就好像我对一个新同事含糊地说一句"你去搜一下",却期待他精准地猜中我到底要他搜什么、用哪个系统、怎么操作。我把"沟通不清楚"的责任,推给了"对方不够聪明";可真相是,无论对方(人或模型)多聪明,含糊的、信息不全的表达,都无法让他做对事——因为他没有读心术,他只能依据你给他的信息去行动。这让我领悟到一个深刻的认知:和 AI(大模型/Agent)协作,本质上是一种"沟通"——而沟通的效果,极大地取决于"你这一方表达得清不清楚、信息给得全不全";当 AI"没做对"时,在抱怨它之前,先反躬自省:"我有没有把我想要的、把它需要知道的,清晰、完整、无歧义地传达给它?";很多时候,AI 的"表现不好",根源是我们这一方"沟通不到位"(prompt 含糊、上下文缺失、工具描述不清)。这其实揭示了 AI 时代一项越来越重要的元能力:"清晰地向 AI 表达意图、提供它所需的信息"——这既是"提示词工程"的核心,也延伸到工具描述、上下文构建等方方面面;它要求我们具备一种"换位到 AI 视角"的能力:想象 AI 看到的只有你给的这些信息,问自己"就凭这些,它能明白、能做对吗?";把"和 AI 清晰沟通"修炼成一项自觉的能力,是用好 AI 的关键。把"AI 没做对"先反思为"我沟通得够清楚吗"、修炼清晰地向 AI 表达和提供信息的能力——这,是我用一次工具描述含糊的事故,换来的、关于 AI Agent、也关于"如何与 AI 协作"的、最朴素也最深刻的领悟。如果这篇复盘,能让你下次发现 Agent 用错工具时,先去看看"是不是我的工具描述没写清楚"、而不是急着怪模型,那我对着那个老选错工具的 Agent 排查的这大半天,就值了。

—— 别看了 · 2026