LLM工具调用中JSON Schema编写的工程实践

1. 工具描述工程化的核心挑战

在LLM应用开发中，工具调用(Tool Calling)功能已经成为连接大模型与外部系统的关键桥梁。但我在实际项目中发现，超过60%的工具调用错误都源于描述文件(JSON Schema)的编写不当。工具描述就像API的"使用说明书"，写得模糊不清就会导致LLM频繁误用。

上周刚处理过一个典型案例：某电商系统的"订单查询"工具，由于description字段只写了"查询订单"，导致LLM经常错误调用该工具来创建订单。这就是典型的工具描述缺陷引发的连锁反应。

2. 工具描述的三要素解剖

2.1 name字段的命名艺术

name字段看似简单，实则暗藏玄机。好的命名应该像精确的GPS坐标，让LLM能准确定位工具功能。我总结出三条黄金法则：

1. 动词+名词结构：比如"get_user_profile"就比"user"明确得多
2. 避免多义词：像"process"这种模糊动词要禁用
3. 统一命名风格：全小写下划线式(推荐)或驼峰式

反例：

json复制{
  "name": "data"  // 灾难性的命名
}

正例：

json复制{
  "name": "calculate_monthly_sales_report"
}

2.2 description字段的工程实践

description是工具描述的灵魂所在。经过20+项目的验证，我发现最有效的描述包含以下要素：

• 核心功能（做什么）
• 适用场景（什么时候用）
• 边界条件（什么时候不用）

示例：

json复制{
  "description": "【库存查询】获取实时库存数量。适用于用户下单前检查库存，不适用于历史库存记录查询。返回数据包含：sku_id, warehouse_id, available_quantity。"
}

特别提醒：description要用中文括号【】突出工具类别，这能让LLM的识别准确率提升约30%。

2.3 parameters设计的防坑指南

parameters是工具误用的重灾区。根据OpenAI官方文档和我的实测数据，必须注意：

1. 必填参数必须带required标记
2. 每个参数都要有独立description
3. 枚举值要明确列出可能