Agent 工具调用总失败？函数调用的调试清单

做 Agent 开发，工具调用失败是最常见的坑。我的调试清单：

1. Schema 要严格：参数类型、必填项、枚举值定义清楚，模型才能正确填；
2. 描述要写人话：工具描述是给模型看的文档，别写开发者黑话；
3. 错误要可读：工具返回的错误信息要能让模型理解并重试；
4. 加幂等：Agent 会重试，有副作用的工具一定要幂等；
5. 记日志：完整记录调用链，出问题才能复现。

经验上，60% 的失败是 schema 定义不清晰导致的，不是模型能力问题。

大家还遇到过什么坑？

调试清单里建议加一项：工具的超时和重试策略。Agent 会重复调用超时的工具，不设上限会烧掉大量 token。

还有一点很重要：工具描述里的示例（few-shot）比文字描述更有效。我们在 description 里加了输入输出示例后，调用准确率明显提升。