调试指南

tool calling 出问题时，最容易卡在这五类地方：

1. 模型根本没调用工具

检查：

tool description 是否足够明确
tool_choice 是否被设置成 none
用户问题是否真的需要外部能力
工具是不是太多，导致模型选择困难

2. arguments 解析失败

常见原因：

返回的是字符串化 JSON
字段缺失
枚举值不合法
SDK 帮你包了一层对象

建议：

先完整打印原始响应
在宿主侧做 schema 校验
对解析异常做单独日志分类

3. 工具执行失败

检查：

网络超时
权限不足
本地环境缺依赖
参数映射错误

推荐返回结构化错误，不要只丢异常字符串。

4. 回填消息格式不对

很多循环失败不是工具没跑，而是结果回填格式错了。

比如：

OpenAI 的 tool_call_id 没带
Anthropic 的 tool_result content block 格式不对
SDK 期待对象，结果你传了字符串

5. 模型陷入重复调用

可能原因：

工具结果不够清晰
模型没意识到任务已完成
tool result 没给明确结束信号
没有限制最大调用轮次

建议结合这些页面一起排查