Q38 · 工具描述（Tool Description）应该怎么写？

用户问客服智能体：“订单 A123 的耳机能退吗？”系统里有两个可读数据源：一个查订单，另一个查退货政策。模型必须先找到 A123 的订单事实，再根据订单里的商品类别查适用政策。如果给两个工具的说明都只写“查询信息”，模型可能选错工具、把订单号填进商品类别，或者在没有查到订单时直接猜一个结论。

工具描述就是提供给模型看的接口说明。它要让模型判断：这个工具负责什么问题、什么时候用、输入字段填什么、结果会是什么、它不能做什么。工具描述通常与可机读的参数结构一起提供；模型提出调用请求后，真正执行数据库查询的是应用程序。OpenAI 的函数调用文档展示了 name、description、parameters 和 strict 等字段；Anthropic 的工具定义文档也明确建议描述用途、使用时机及参数含义。OpenAI：Function calling · Anthropic：Define tools

先认清这些词在客服例子里指什么

术语或字段	具体含义	订单 A123 的对应物
Agent / 智能体	用模型决定是否调用工具，并利用工具结果完成用户任务的程序	接收退货咨询的客服程序
工具 / 函数	应用程序暴露的一项能力；模型只能请求调用，执行由程序负责	只读查订单、只读查政策
Tool Description / description	告诉模型工具用途和调用边界的文字	“用订单号查当前用户可访问的订单；不办理退款”
name	稳定、能区分能力的工具名	get_order、get_return_policy
参数 / argument	调用工具时要传入的值	order_id 填 A123
参数结构 / schema	用字段名、类型、必填规则表达输入格式	order_id 必须是字符串
required	调用时必须给出的字段列表	查订单必须有 order_id
additionalProperties: false	不接受结构中未声明的额外字段	不能偷偷加 user_id、refund_amount
strict: true	在支持该设置的 OpenAI 函数调用接口中，要求模型调用遵循所给结构；前提是结构满足该接口的要求	约束请求里有哪些字段，不核实订单归属
工具结果	程序执行后返回的事实或错误	订单类别、签收时间，或 FORBIDDEN
只读 / 有副作用	只读工具只查数据；有副作用的工具会改变外部状态	查订单是只读；提交退款会改变业务状态

这里的 order_id 是订单号，category 是商品类别。两者即便都写成字符串，也不能混填。strict: true 与 additionalProperties: false 只能帮助约束输入的形状；“A123 是不是当前用户的订单”必须由后端核实。OpenAI 文档对严格模式的结构要求包括将属性列入 required，以及设置 additionalProperties: false；不符合要求的严格模式结构会被接口拒绝。OpenAI：Strict mode

模糊说明会把哪一步带偏

假设把一个工具草率写成下面这样：

{
  "name": "get_info",
  "description": "查询订单和退货信息",
  "parameters": {
    "type": "object",
    "properties": {
      "id": { "type": "string", "description": "ID" }
    }
  }
}

get_info 没说是查一笔订单还是查某类商品的政策；id 也没有说明是订单号、商品编号还是用户编号。面对“订单 A123 的耳机能退吗”，模型即使正确抽出 A123，仍无法知道这次调用会返回订单事实还是退货规则。若系统还有一个同样叫“查询信息”的工具，选择会更困难。Anthropic 官方文档给出的差描述示例也是极短的“按股票代码获取股价”；相应的好描述补上了输入代码的要求、返回什么、适用问题与不会提供的内容。Anthropic：工具描述示例

写描述时，先按一项实际工作回答五个问题：它查或改什么？什么时候需要它？输入从哪里来？返回什么？有哪些相邻任务不归它管？ 名称要能区分操作；参数名要表达业务含义；参数说明要讲值的来源、格式和限制。不要只把函数名换一遍写进 description。

给“查订单”一份能被正确使用的说明

先确定业务动作：用户给出订单号时，客服需要核实这笔订单的商品类别、签收时间和状态。因此把只读工具命名为 get_order（获取订单），输入只收 order_id。下面是教学示例，采用 OpenAI Responses API 文档中的函数工具结构；其他提供商的字段包装可能不同，写法应按所用接口调整。OpenAI：定义函数工具

{
  "type": "function",
  "name": "get_order",
  "description": "只读查询当前登录用户可访问的一笔订单。当回答具体订单的商品类别、签收时间或状态需要订单事实时使用。输入用户明确提供的订单号。返回订单状态、商品类别、签收时间和是否未拆封，或返回 NOT_FOUND、FORBIDDEN 等错误。不查询退货政策，不提交退款申请。",
  "strict": true,
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "用户明确给出的订单号，例如 A123；不能填商品类别，也不能猜测缺失的订单号。"
      }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

逐项看这份定义：

1. name 用动词加对象表达动作。模型看到 get_order，知道这是获取订单；程序也用它定位对应实现。不要靠一个 get_info 包办所有查询。
2. 总体 description 写出调用条件和返回范围。用户问的是某笔订单，所以先查订单；用户只问“耳机一般几天可退”而没有具体订单时，就不必调用它。
3. 参数 order_id 的名字和说明一起消除歧义。A123 来自用户原话；如果用户没有给订单号，而系统也没有可信的订单上下文，就询问订单号或提供一般政策，不能编一个。
4. required 和类型限制是格式规则。示例没有把 user_id 暴露给模型：当前登录用户的身份由服务端会话取得，查询时还要检查订单归属。工具描述中“当前登录用户可访问”是行为提示，不是授权机制。
5. “不查询政策、不提交退款申请”把邻近能力划开。即使模型把查订单叫对了，也不能从订单字段直接推导政策，更不能把只读调用说成已经办理退款。

工具输出同样要设计清楚。成功时可返回 {"status":"OK","order_status":"DELIVERED","category":"earphone","signed_at":"2026-09-23","unopened":true}；失败时返回结构化错误码，如 {"status":"FORBIDDEN"} 或 {"status":"NOT_FOUND"}。这里 status 表示调用结果，order_status 表示订单已送达；category 是政策查询要用的类别；signed_at 是签收日期；unopened 表示是否未拆封。不要把“查不到”和“工具超时”都写成空字符串，否则模型无法决定是向用户核实、稍后重试，还是说明无权限。上述字段和日期均为本例假设数据，不是某个真实商家的政策。

再写“查政策”，让两种工具各管各的

第二项业务动作是按商品类别读取当前有效的退货条款，因此命名为 get_return_policy（获取退货政策）。输入的 category 应来自订单查询结果，或者用户明确指定且系统能识别的类别；不要把 A123 当类别传入。

{
  "type": "function",
  "name": "get_return_policy",
  "description": "只读查询某商品类别当前有效的退货政策。当需要确认退货期限、商品状态要求或例外条款时使用。输入规范商品类别，返回有效政策版本、起算点、期限和条件，或返回 UNKNOWN_CATEGORY、UNAVAILABLE 等错误。不查询任何订单，也不判断某一订单是否最终获准退货。",
  "strict": true,
  "parameters": {
    "type": "object",
    "properties": {
      "category": {
        "type": "string",
        "description": "商品类别标识，优先使用 get_order 返回的 category，例如 earphone；不能填订单号或凭商品名称猜测类别。"
      }
    },
    "required": ["category"],
    "additionalProperties": false
  }
}

这两个工具的差异不只是名字：get_order 用订单号查订单事实，get_return_policy 用商品类别查政策规则。前者返回的 category 正好成为后者的输入，但“查询政策”仍不能代替“判断订单是否符合所有条件”。政策的版本和生效日期应由服务端按当前时间或明确的业务时间读取，输出中给出供核对的版本信息；不要让模型从记忆里假定规则永远不变。

图中只画了工具选择与参数传递：A123 对应 order_id，订单返回的 earphone 对应 category。实际答复还需要解释政策起算点、例外条件、数据是否齐全；图上的两个工具都没有办理退款的权限。

跟着 A123 走一遍正常与失败路径

假设演示系统的政策是：“该类别商品自签收次日起 7 个自然日内，未拆封且无其他例外时，可以申请退货。”当前日期假定为 2026-09-26，订单 A123 的签收日是 2026-09-23。这里的规则和日期只用于说明调用顺序，不代表通用法律或平台规定。

步骤	模型提出的请求或程序返回的结果	这一步确认了什么
用户提问	“订单 A123 的耳机能退吗？”	有具体订单号，也问到了退货资格
查订单	get_order({"order_id":"A123"})	后端核实当前登录用户可访问 A123
订单结果	OK，order_status=DELIVERED，category=earphone，signed_at=2026-09-23，unopened=true	有可核对的商品类别与订单条件
查政策	get_return_policy({"category":"earphone"})	用订单给出的类别查规则
政策结果	当前有效版本规定：签收次日起 7 个自然日，未拆封，且无其他例外	可以把订单事实与政策条件逐项比较
答复	“按当前查到的规则和订单信息，A123 在期限内且显示未拆封，初步符合申请条件；最终结果仍以实际审核及例外条款为准。”	说明证据和结论范围，未声称已提交退款

失败路径更能检验描述是否写清。若 get_order 返回 FORBIDDEN，程序或模型应停止读取这笔订单的细节，并提示用户在有权访问的账号中核实订单；不能改用其他工具绕过权限。若返回 NOT_FOUND，可以请用户确认订单号。若 get_return_policy 返回 UNAVAILABLE，表示政策服务暂时不可用，此时不能把服务故障解释为“没有退货政策”，更不能凭模型记忆给出确定期限。若用户问“请帮我直接退款”，两个只读工具只能支持查询与解释；要执行退款，系统必须另有明确授权和确认的写入流程。

描述写到哪里，程序必须守到哪里

工具描述影响模型如何提出调用；服务端决定调用是否允许执行。一个写了“只查询本人订单”的描述，无法阻止伪造 order_id；后端仍要用登录态检查订单归属，校验参数取值、控制可调用工具集合，并记录敏感操作。对会改变状态的工具，还应设置确认、幂等或审批规则，不能靠描述里的“请谨慎”当保护。OpenAI 文档中的 tool_choice 可控制模型是否、或从哪些工具中选择；这属于应用配置，和自然语言描述互补。OpenAI：控制工具选择

准备上线时，可以拿真实咨询方式做小型测试集，而不是只看描述是否“文采好”：给出“订单 A123 的耳机能退吗”“耳机一般退货期限是什么”“订单号忘了”“A123 是别人的订单”“政策服务超时”等输入，观察选中的工具、参数、无权限时是否停止、答案有没有超出工具结果。若常把 A123 填进 category，先改参数名、来源说明和工具边界；若已经正确选工具仍泄露他人订单，就修后端授权，不能只改文案。

面试时怎样说

“我会把 Tool Description 当成模型能读懂的接口契约来写。名称先区分动作与对象；描述说明工具做什么、什么时候调用、返回什么，以及相邻但不负责的工作；每个参数写清业务含义、值从哪里来和格式限制，并用 schema 表达类型与必填项。比如客服问 A123 能否退货，先用订单号查订单，再拿订单返回的商品类别查政策，不能把订单号当成类别。错误结果也要能区分无权限、查无此单和服务不可用。最后用真实问法测试工具选择和参数，但权限、身份校验、写操作确认必须由应用程序保证，不能靠描述文字保证。”

如果面试官追问“描述越长越好吗”，可以回答：信息要完整，但每句话都应帮助模型决定调用或填参。 先覆盖用途、触发条件、参数、返回与边界，再删掉重复背景和空泛形容；描述过长会增加上下文成本，也可能把关键条件淹没。对于格式容易混淆的参数，可提供与 schema 相符的输入示例；对于涉及用户身份或资金的操作，示例也不能代替服务端验证。Anthropic：工具输入示例