description写成“处理订单”Agent永远不触发，触发条件和“什么时候不能用”到底该怎么写？

工具描述工程 · 触发语义密度 · 负向约束 · 评测闭环

摘要：工具调用型 Agent 的失败，多数不是模型“不会做”，而是模型“不知道何时该做”。当工具 description 只写“处理订单”这类名词性短语时，它既没有可匹配的意图信号，也没有可判别的边界条件，模型在候选工具集合中无法建立稳定的选择偏好，最终表现为“永不触发”或“错误触发”。本文以“触发语义密度”为核心分析主线，把工具描述拆为意图锚点、参数契约、前置条件、负向边界、失败语义五个可度量维度，给出从诊断、改写、评测到回归的完整工程路径，并讨论多工具竞争、长上下文衰减、描述注入风险等边界条件。

目录

一、问题的本质：不是模型能力，而是选择信号缺失

先把现象还原成一个可检验的命题。一个典型的工具调用型 Agent，其运行时循环大致是：系统提示给出角色与约束，工具清单以结构化 schema 注入上下文，用户输入到达后，模型输出一个工具调用（名称 + 参数）或直接回答，执行结果回填上下文，循环直至终止。在这个循环里，模型对“是否调用某工具”的决策，本质上是一次在候选工具集合上的条件选择：给定对话状态与工具描述，估计每个工具被正确使用的后验概率。

当 description 只有“处理订单”四个字时，这个条件选择失去了几乎全部判别信息。它没有说明输入是什么形态（订单号？自然语言诉求？批量文件？），没有说明输出是什么（查询结果？状态变更？退款发起？），没有说明何时应当优先于其他工具，也没有说明何时必须拒绝。模型面对的是一个语义上高度欠定的标签，只能依赖工具名做字面匹配，而工具名往往又是内部命名习惯的产物（如 order_svc_v2），与用户表达之间不存在稳定映射。

笔者认为，把这类失败归因为“模型不够聪明”是一种诊断上的懒惰。更准确的表述是：工具描述是模型可见的唯一“接口文档”，描述的信息量直接决定了选择的可辨识度。这与信息检索中的查询-文档匹配问题同构：如果文档只有标题没有正文，检索质量的上限就被锁死了。工具描述工程要做的，是把这份“接口文档”从标签升级为规格说明。

本文评述：业界大量“Agent 不听话”的案例，在排查顺序上都应先看工具描述而非提示词。提示词影响的是“要不要用工具”，工具描述影响的是“用哪一个、怎么用、什么时候别用”。二者混淆会导致大量无效调参。

还有一个常被忽略的机制：工具描述在上下文中并非孤立存在，它与系统提示、历史消息、其他工具描述共同竞争注意力。描述越短越模糊，模型越倾向于用“通用对话能力”兜底，表现为不调用任何工具而直接编造回答——这比报错更危险，因为错误被静默吞掉了。关于工具调用失败的分类与排查，可参考 Anthropic 官方的工具使用文档（docs.anthropic.com/en/docs/build-with-claude/tool-use）与 OpenAI 的函数调用指南（platform.openai.com/docs/guides/function-calling），两者都明确建议在描述中写清用途与适用场景。

二、触发语义密度：一个可度量的描述质量框架

为了让“描述写得好不好”从主观判断变成可讨论的工程问题，本文提出触发语义密度（Trigger Semantic Density, TSD）这一分析概念：单位描述长度内，能够帮助模型区分“该调用/不该调用”的判别性信息量。它不是严格的数学量，而是一个用于诊断与比较的启发式指标，可按五个维度打分（每维 0–2 分，总分 10 分）。

按此框架，“处理订单”的得分约为 1–2 分：意图锚点几乎为零，参数契约缺失，前置条件与负向边界完全空白，失败语义未定义。而一份合格的描述通常在 7 分以上。需要强调，TSD 不是越长越好——堆砌无关信息会稀释注意力，反而降低判别性。真正的目标是提高单位长度内的判别信息占比，而非单纯增加字数。

本文评述：TSD 的价值不在于精确打分，而在于把“描述质量”拆成可分别改进的子问题。工程实践中，团队常陷入“整体重写”的低效循环；按维度拆解后，可以定点修复最短板，并用小样本评测验证单点改动是否有效。

关于工具描述对模型行为的影响，已有若干实证工作可供参考。Schick 等人在 Toolformer 工作中展示了模型可通过少量示例学习何时调用外部工具（Schick et al., 2023, arXiv:2302.04761）；Qin 等人在 ToolLLM 中系统讨论了 API 文档质量对调用成功率的影响（Qin et al., 2023, arXiv:2307.16789）。这些工作共同指向一个结论：工具的可发现性与文档的判别性正相关。延伸阅读可参考 LangChain 关于工具定义的官方教程（python.langchain.com/docs/how_to/custom_tools）。

三、触发条件怎么写：从名词短语到可判别谓词

触发条件的写作目标，是让模型能在用户话语中找到一个可判别的谓词信号。名词短语（“订单”“退款”）描述的是领域对象，谓词（“查询某订单当前状态”“为已支付订单发起全额退款”）描述的是可执行动作及其成立条件。模型做选择时匹配的是后者。

3.1 三段式结构：用途—触发—输入

一个可直接套用的最小结构是：第一句写“这个工具做什么、产出什么”，第二句写“在什么用户意图下应当优先选择它”，第三句写“需要哪些输入、缺失时怎么办”。三段各司其职，避免混写。下面是一个对照示例。

# 反例：信息量不足
description: 处理订单

# 正例：三段式
description: >
  查询指定订单的当前状态与物流节点，返回结构化状态对象。
  当用户询问“我的订单到哪了”“这个单发货了吗”“订单为什么还没到”
  等关于单个订单进度的问题时，优先调用本工具。
  输入 order_id 为 12 位数字字符串；若用户未提供，先追问，不要猜测。
  本工具只读，不修改订单状态；涉及取消、退款、改地址请改用对应工具。

注意正例中“优先调用本工具”与“不要猜测”两句。前者提供了选择偏好，后者提供了行为约束。二者共同把模糊的标签变成了可执行的决策规则。笔者认为，这类“行为指令句”是描述中最容易被省略、却对触发率影响最大的部分。

3.2 意图锚点的写法：覆盖表达变体而非罗列同义词

意图锚点的常见误区是把同义词表塞进描述（“查询、查找、检索、搜索、查看”）。这种做法收益有限，因为模型对同义表达的泛化能力本就不弱，真正缺的是场景化句式。更有效的写法是给出 2–4 条贴近真实用户话语的例句，覆盖不同信息完整度：信息完整（含订单号）、信息缺失（需追问）、口语化（“我那个快递咋还没动静”）。

这里有一个可验证的工程判断：例句应当来自真实日志的脱敏采样，而非编写者臆想。若团队有线上对话日志，抽取目标工具应触发但未触发的样本，把其中的用户原话摘 3–5 条放进描述，通常能显著改善召回。这是“用失败样本反哺描述”的闭环做法，比凭空扩写更可靠。

3.3 参数契约：把“字段名”升级为“取值规格”

参数描述同样影响触发。若某必填参数在描述中没有任何格式说明，模型在用户未提供时会倾向于编造一个看似合理的值，而不是追问。正确的写法是显式声明格式、来源与缺失策略。下表给出一组常见参数的规格写法参考（模拟示例，用于说明格式，非真实业务数据）。

本文评述：参数契约的强描述不仅提升调用正确率，还降低了“参数幻觉”的治理成本。很多团队在输出侧加校验规则来兜底，但如果输入侧描述已明确“缺失即追问”，大部分幻觉根本不会产生。防线应当前移。

四、“什么时候不能用”：负向边界的四种写法

负向边界是描述工程中最被低估的部分。只写“能做什么”会让工具在语义邻近的场景中被误触发，而误触发的代价往往高于不触发——它可能造成状态变更、资金操作或数据泄露。负向边界的核心是回答三个问题：什么情况下明确不该调用、应该改用什么、如果强行调用会有什么后果。

4.1 排他式：列出语义邻近但不应使用的场景

排他式写法直接点名易混淆场景。例如订单查询工具应写明“不适用于修改收货地址、不适用于发起退款、不适用于批量导出”。这类句子短、判别性强，适合放在描述末尾作为“边界声明”。它的作用是切断模型基于关键词（“订单”）产生的过度泛化。

4.2 条件式：用前置状态约束调用

条件式写法把调用与业务状态绑定：“仅当订单状态为已支付或已发货时可用；订单已取消时返回明确错误而非空结果。”这类约束需要模型理解状态机，因此描述中应给出状态枚举，避免模型自行推断。对于状态复杂的业务，建议在描述中附一行状态流转摘要。

4.3 转交式：给出替代工具的名称

转交式写法是负向边界中收益最高的一种：不只说“不要用我”，还说“请改用 X”。这相当于在工具之间建立了路由提示，能显著降低多工具场景下的选择混乱。写法上应使用与工具清单中完全一致的名称，避免模型做名称映射时出错。

4.4 后果式：说明误用的风险

后果式写法用于高风险工具，明确写出误调用可能造成的不可逆后果（“本工具会真实发起退款，不可撤销，仅在用户明确确认退款金额后调用”）。这类句子相当于在描述层嵌入了一道确认门槛，对降低误操作率有直接作用。笔者认为，凡涉及写操作、资金、对外发送的工具，后果式描述应视为强制项而非可选项。

实践提示：负向边界不要写成大段否定句堆叠，否则模型容易把否定词与工具本身错误关联。推荐“场景 + 应改用 + 后果”的三元短句，每条一行，控制在 3–5 条。

关于工具选择中的混淆问题，可参考 Gorilla 项目对 API 调用幻觉的系统评测（Patil et al., 2023, arXiv:2305.15334），其结论之一是检索增强能缓解但无法消除邻近 API 的误选，这与本文强调“描述内建路由提示”的判断一致。另有 Berkeley Function Calling Leaderboard 持续跟踪各模型在多工具场景下的选择准确率（gorilla.cs.berkeley.edu/leaderboard.html），可作为选型参考。

五、多工具竞争与描述互斥性设计

单工具场景下，描述写得再差也只是“不触发”；多工具场景下，问题升级为“选错”。当工具清单中存在多个语义邻近的工具（查询订单、查询物流、查询售后进度），描述之间若缺乏互斥性设计，模型会在三者间随机漂移。解决思路不是逐个优化，而是成组设计描述，使任意两个工具在意图锚点上可区分。

具体做法分三步。第一步，列出所有语义邻近工具，画出它们的意图重叠区。第二步，为每个重叠区指定唯一归属工具，其余工具在描述中显式让渡（“物流节点问题请用 query_logistics，本工具只返回订单级状态”）。第三步，用一组“最小对立对”测试样本验证：同一句用户话语，在描述成组调整前后，选择结果是否稳定指向归属工具。

# 最小对立对测试样本（模拟数据，用于说明方法）
cases = [
  {"q": "我上周买的耳机到哪了",        "expect": "query_logistics"},
  {"q": "这个订单现在是什么状态",      "expect": "query_order"},
  {"q": "退款申请审核到哪一步了",      "expect": "query_aftersale"},
  {"q": "帮我看看单号 1234... 的进度", "expect": "query_logistics"},
]
# 评估指标：exact-match 选择准确率 + 误选矩阵

本文评述：互斥性设计的本质是把“模型的选择问题”转化为“描述设计者的分工问题”。凡是能在描述层用一句话划清的边界，都不应留给模型在推理时自行权衡——后者不稳定、不可审计，且随上下文长度增加而退化。

长上下文衰减是另一个现实约束。当工具数量上升到数十个，描述总长度可能挤占有效上下文，模型对靠后工具描述的注意力下降。工程上的缓解手段包括：按会话阶段动态裁剪工具清单、把高频工具的触发例句前置、对工具描述做分层（首行摘要 + 展开细节）。这些手段的取舍需要用评测数据支撑，而非凭感觉。关于上下文长度对检索与选择的影响，可参考 Lost in the Middle 的实证研究（Liu et al., 2023, arXiv:2307.03172），其发现相关信息位于上下文中部时利用率最低，这一结论对工具清单排序有直接启示。

六、评测闭环：如何证明改写真的有效

描述改写如果没有评测，就只是文风调整。一个可操作的评测闭环包含四个环节：样本构建、指标定义、对照实验、回归看护。

样本构建：从线上日志与人工构造两条来源采集。线上样本保证分布真实，人工样本补齐长尾与对抗场景（信息缺失、指代模糊、多意图混合）。每条样本标注期望工具与期望行为（调用/追问/拒答）。规模上，单工具 50–100 条即可获得有参考价值的信号；多工具竞争场景建议每对邻近工具至少 30 条最小对立对。

指标定义：至少跟踪四项——触发召回率（应触发中实际触发比例）、误触发率（不应触发中实际触发比例）、参数正确率（必填参数取值正确比例）、追问率（信息缺失时正确追问比例）。四项指标存在张力：提高召回往往推高误触发，因此需要设定业务可接受的操作点，而非追求单项最优。

对照实验：同一批样本，分别用旧描述与新描述运行，固定模型版本与温度参数，多次采样取均值以降低方差。若条件允许，做消融——只加意图锚点、只加负向边界，分别观察指标变化，从而定位哪类信息贡献最大。

回归看护：把评测集纳入 CI，任何描述变更触发全量回归。描述是生产资产，应当像代码一样被版本管理、被测试覆盖。这一点在多数团队中仍是空白。

本文评述：上述阈值仅为示例，真实操作点必须由业务风险决定。查询类工具可以容忍较高误触发（代价是多一次只读调用），而写操作工具应把误触发压到极低，宁可牺牲召回、改为追问。用一套阈值管理所有工具，是评测设计中最常见的错误。

七、边界条件、失效模式与安全风险

任何描述工程都有其作用边界，夸大其词会误导实践。第一类边界是模型能力上限：当任务本身需要多步推理或外部知识时，描述再清晰也无法让模型完成它做不到的事。描述解决的是“选择与路由”，不解决“执行能力”。第二类边界是业务状态不可见：若工具依赖的状态未在上下文中提供，模型只能追问或猜测，描述只能规定“应追问”，无法替代状态注入。

失效模式方面，至少有三类值得警惕。其一是描述注入：若工具描述可由第三方配置，恶意内容可能借描述进入系统提示的信任域，诱导模型越权调用。缓解手段包括描述来源白名单、变更审计、以及对描述中指令性语句的人工复核。其二是过度约束导致的僵化：负向边界写得过密，模型可能对合法请求也拒绝调用，表现为“该用不用”。其三是描述与实现漂移：工具行为升级但描述未同步，模型按旧描述调用，产生参数错误或语义错配。这要求描述与代码同仓管理、同步评审。

安全与合规层面，涉及个人数据的工具应在描述中声明数据处理边界（如“仅返回脱敏后的物流节点，不返回收件人手机号”），涉及资金操作的工具应声明确认要求。这些声明不能替代后端鉴权，但能降低模型层的越权倾向。关于 Agent 安全与工具滥用的系统性讨论，可参考 OWASP 关于 LLM 应用风险的条目（owasp.org/www-project-top-10-for-large-language-model-applications），其中对过度代理权限（Excessive Agency）的界定与本文的负向边界设计直接相关。

笔者认为，描述工程应当被纳入 Agent 系统的变更管理流程，而不是散落在各个工具实现者的个人习惯里。一个可落地的组织做法是：建立描述模板与评审清单（意图锚点、参数契约、前置条件、负向边界、失败语义五项逐条勾选），把 TSD 五项作为 PR 评审的固定检查项。这比任何单次改写都更能保证长期质量。

八、结论与展望

回到最初的问题：description 写成“处理订单”，Agent 为什么永远不触发？因为这句话没有提供任何可用于条件选择的判别信号——它既没说何时该用，也没说何时不该用，更没说输入输出长什么样。修复路径不是换更贵的模型，而是把描述从标签升级为规格说明：用三段式给出用途与触发场景，用场景化例句覆盖表达变体，用参数契约阻断幻觉，用四类负向边界划清禁用区，用成组互斥设计解决多工具竞争，最后用评测闭环证明改动有效。

展望来看，工具描述正在从“人写给模型看的文档”演化为“可被自动优化与验证的接口契约”。已有研究探索用执行反馈自动改写工具文档、用检索动态注入相关工具子集，这些方向与本文的 TSD 框架并不冲突，反而可以互补：自动优化需要一个可度量的目标函数，而 TSD 提供了拆解维度。对工程团队而言，当下最务实的动作是建立描述模板、评测集与回归机制这三件基础设施——它们不依赖模型迭代，却能持续兑现收益。

一句话总结：工具描述不是注释，是模型做决策时唯一能读到的接口规格。写清“何时用、怎么用、何时别用”，比任何提示词技巧都更接近问题的根因。

主要参考文献

文章声明