Agent 跑 demo 时行云流水，一上真实任务就“工具调用失败”刷屏：参数缺了、格式错了、超时了……我整理了一份调试清单，按这个顺序查，八成问题半小时内定位。

## 一、schema 设计：先怀疑描述

- 字段描述写给模型看，不是给人看的：“ISO 8601 日期，如 2026-10-13”比“日期字符串”好十倍。
- 必填 / 可选分清楚，可选字段给默认值或写明缺省行为。
- 枚举值列全：status 只有 success / failure 两种就别让模型猜。
- 参数超过 6-7 个就拆工具，模型一次填不准那么多。

## 二、参数校验：错在边界

- 类型对了值错了最常见：字符串里塞数字、日期格式混用。服务端做宽松解析 + 严格校验，报错信息直接告诉模型“期望什么、收到了什么”。
- 空值和超长先拦：超长参数既浪费 token 又容易出意外。

## 三、错误重试：别无脑重试

- 区分可重试（超时、限流、临时 5xx）和不可重试（参数错误、权限不足）：后者重试一百次也没用。
- 重试带退避 + 抖动，限流时别顶着 429 硬冲。
- 把上次的错误信息塞回给模型再试一次，很多“参数错误”是模型没看清，重述一遍就对了。

## 四、日志追踪：把调用链留下来

每次工具调用记：时间、工具名、入参（脱敏后）、出参摘要、耗时、模型原始输出。线上翻车时，没有这份日志就是盲人摸象。

## 实战建议清单

1. schema 描述写示例，别写抽象定义。
2. 参数超过 7 个就拆分工具。
3. 服务端校验报错要“说人话”，指明期望格式。
4. 重试只给可重试错误，加退避。
5. 错误信息回填给模型再试一次。
6. 全链路日志，入参脱敏。

你遇到过最离谱的一次工具调用失败是什么原因？评论区交流下。