工具的描述和参数怎么写，模型才能选对工具？

详细解析#

模型是怎么"看到"工具的#

每次请求，工具定义都会和对话一起发给模型。选哪个工具、参数怎么填，模型全靠这些文字判断，它看不到你的代码。写工具定义就像给一位新同事写接口文档：他没读过源码，只能读文档。

描述要平实、准确，和工具的真实行为一致，不要靠"必须""一定要"这类强硬措辞催模型调用。Anthropic 在自家模型的提示词建议里提到，有的模型对指令更敏感，为防止漏调而写的强硬措辞反而会让它在不需要时也去调用，改成"在……时使用"这样的平实说法即可；其他模型是否如此，要用评测验证。各家接口对工具名的字符和长度有限制，只用字母、数字、下划线和连字符最稳妥。

参数怎么约束#

• 能枚举就用 enum：订单状态、排序方式这类固定取值，不要让模型自由发挥
• 分清必填和可选：真正必需的才放进 required，可选参数在描述里说明不传时的行为
• 格式写进描述：format: "date" 这类关键字不是每个平台都会遵守，描述里再写一句"格式 YYYY-MM-DD"更稳妥
• 默认值在代码里兜底：JSON Schema 的 default 只是说明，模型可能不传，执行时要自己补上
• 写明单位和时区：金额是元还是分，时间按哪个时区
• 少用深层嵌套：层级越深，模型越容易填错

避免功能重叠#

同时有 search_orders 和 query_orders，或者三个只差一个查询条件的工具，模型只能靠猜。两种处理方式：

• 合并成一个工具，用参数区分，比如 find_user 加一个取值为 email、phone 的 by 参数
• 确实要分开时，在各自的描述里写清分工："已知订单号用 get_order，按条件筛选用 search_orders"

返回值也要设计#

工具结果会进入上下文，直接影响模型的下一步：

• 只返回完成任务需要的字段，内部 ID、调试信息不要带
• 把状态码转成可读的值，比如把 status: 3 转成"已发货"
• 结果太多时截断，并说明总数和翻页方式："共 230 条，只返回前 20 条，可传 page 参数翻页"
• 出错时返回能指导修正的信息，见 工具调用出错了怎么处理

代码示例#

同一个工具，写得差和写得好的对比（通用格式，各家 SDK 外层的字段名不同）：

{
  "name": "orders",
  "description": "查询订单",
  "parameters": {
    "type": "object",
    "properties": {
      "q": { "type": "string" },
      "status": { "type": "string" },
      "date": { "type": "string" }
    }
  }
}

名称看不出动作，描述没有边界，参数没有说明：status 能填什么、date 是什么格式全靠猜，返回什么也没写。

{
  "name": "search_orders",
  "description": "按条件筛选当前登录用户的订单，返回订单号、商品名、金额（元）、状态和下单时间，按时间倒序，最多 20 条。用户问\"我的订单\"\"最近买了什么\"时使用。已知订单号时改用 get_order。",
  "parameters": {
    "type": "object",
    "properties": {
      "keyword": { "type": "string", "description": "商品名关键词，如\"耳机\"。可选" },
      "status": {
        "type": "string",
        "enum": ["unpaid", "paid", "shipped", "completed", "refunded"],
        "description": "订单状态。可选，不传表示全部状态"
      },
      "since": { "type": "string", "description": "起始日期，格式 YYYY-MM-DD。可选，不传表示最近 30 天" }
    }
  }
}

参数里没有 userId：工具只查当前登录用户的订单，身份由服务端从登录态获取，模型没法指定别人。

面试官可能追问#

易错点#

• 描述只有一句话，没写"什么时候不该用"，相似的工具互相抢调用
• 默认值只写在 Schema 的 default 里，执行代码没处理模型不传参数的情况
• 把下游接口的完整响应原样返回，大量无关字段淹没了关键信息