Function Calling 踩坑复盘：工具定义的 10 个常见错误
一、"明明传了参数，LLM 却说参数缺失"——Function Calling 的第一道坎
Function Calling 看起来简单：定义 Tool Schema，LLM 输出 JSON，代码解析并执行。但实际落地时，错误率比预期高得多。在一个客服 Agent 项目中，3 个月内遇到了 47 种不同的工具调用错误，其中 10 种占据了 90% 的错误量。
这些错误不是 LLM 本身的 Bug，而是 Tool 定义和执行防护的"工程欠债"。以下是 10 个最高频的错误和修复方案。
二、10 个常见错误分布
三、Top 5 高频错误详解
错误 1：Tool 描述模糊导致选错工具
问题：定义了query_order和query_refund两个工具，描述分别是"查询订单"和"查询退款"。用户问"我上周的退款处理好了吗"，模型调用了query_order而不是query_refund。
根因：描述中缺少关键的区分性信息。修复后：
query_order: 根据订单ID查询订单详情（商品、金额、状态）。 不支持查询退款信息。参数：order_id (必需) query_refund: 根据订单ID查询退款记录（退款金额、退款状态、 退款时间）。仅用于查询退款信息。参数：order_id (必需)关键原则：每个 Tool 的描述要写明"做什么"和"不做什么"。模型需要"负面示例"来避免误调用。
错误 2：枚举值未在描述中列出
问题：update_order_status的参数status只定义了类型string，没有列出可选值。模型传了"取消"但系统只认"cancelled"。
修复：在参数描述中显式列出所有枚举值：
status: 订单新状态。必须是以下之一: "pending"(待支付), "paid"(已支付), "shipped"(已发货), "cancelled"(已取消), "refunded"(已退款)。不支持中文状态值。错误 5：JSON 格式错误
这是最高频的执行期错误（约 15% 的调用）。模型有时会输出不合法的 JSON（末尾多了逗号、字符串用了单引号）。修复方式不是优化 Prompt，而是在代码层对 JSON 做容错解析：
// 容错解析 JSON：自动修复常见格式错误 func robustJSONParse(raw string, target interface{}) error { // 1. 尝试直接解析 if err := json.Unmarshal([]byte(raw), target); err == nil { return nil } // 2. 尝试修复常见错误 fixed := raw // 去掉尾部多余的逗号 fixed = regexp.MustCompile(`,(\s*[}\]])`).ReplaceAllString(fixed, "$1") // 单引号替换为双引号（仅限 JSON key/value 部分） // ... 更多修复规则 return json.Unmarshal([]byte(fixed), target) }错误 8：超时未处理
Tool 调用外部 API（如 CRM 查询客户信息）时，API 响应可能 10 秒都回不来。如果 Agent 的主链路被 block 住等待这个 Tool，整个对话会超时。修复：
func safeToolCall(ctx context.Context, tool func(...) (*Result, error), timeout time.Duration) (*Result, error) { ctx, cancel := context.WithTimeout(ctx, timeout) defer cancel() resultCh := make(chan *toolResult, 1) errCh := make(chan error, 1) go func() { result, err := tool(...) if err != nil { errCh <- err return } resultCh <- &toolResult{data: result} }() select { case result := <-resultCh: return result.data, nil case err := <-errCh: return nil, fmt.Errorf("工具执行失败: %w", err) case <-ctx.Done(): return nil, fmt.Errorf("工具执行超时(%v): 返回降级结果", timeout) } }错误 10：错误结果被模型采信
某个 Tool 返回了数据查询错误（如"数据库繁忙"），但 LLM 把这个错误当作了"查询结果"——告诉用户"你的订单号是'数据库繁忙'"。修复：
// 对所有 Tool 返回做结构化包装 type ToolResponse struct { Success bool `json:"success"` Data interface{} `json:"data,omitempty"` Error string `json:"error,omitempty"` } func wrapToolResponse(result interface{}, err error) ToolResponse { if err != nil { return ToolResponse{ Success: false, Error: fmt.Sprintf("工具执行失败，请稍后重试。(错误码:INTERNAL_ERROR)"), // 不暴露原始错误信息给模型（防止幻觉输出） } } return ToolResponse{Success: true, Data: result} }四、系统性预防方案
Schema 规范文档：制定统一的 Tool Schema 编写规范，模板包含：名称（动词_名词）、场景（何时使用/何时不使用）、参数（类型+必填+枚举值+格式示例）、示例（至少 3 个成功调用示例 + 2 个不应调用的示例）。
调用前校验：Service 层对 LLM 输出的 Tool Call 做校验（参数类型、枚举值、必填检查），校验失败时返回格式化错误给 LLM，让它重新生成，而不是直接抛出异常。
调用后守护：Tool 执行结果在返回给 LLM 前，通过规则检查输出是否合理（如金额不能为负数、时间不能是未来、字符串不能包含明显的 SQL 错误信息）。
统计面板：用 Grafana 面板追踪每个 Tool 的调用成功率、平均耗时、参数错误类型分布。排名前 3 的错误类型必须在下个迭代修复。
五、总结
Function Calling 的坑主要集中在"定义"和"防护"两个阶段。定义阶段要遵循"精确描述 + 明确边界 + 枚举值 + 示例"的原则，防护阶段要有"调用前校验 + 调用中超时 + 调用后审核"的三段保护。10 个常见错误中的大部分（描述模糊、JSON 格式、枚举值缺失等）是可以在工程层面系统性避免的——不需要模型升级，只需要更规范的 Tool Schema 设计和更健壮的解析代码。核心认知：不要把 LLM 的输出当作"可信的"，把它当作"可能是对的，必须验证的"。
