Agent 靠工具调用（tool calling）读写文件、跑命令、查接口。失败时，控制台往往只丢一句「tool error」，排障却可能停在错误层。
本系列叫「Agent 工程笔记」。第一篇只建立排查顺序：先分清失败发生在哪一层，再决定改提示、改 schema，还是改环境。
一、先说一个具体麻烦
你让 Agent「更新依赖并跑测试」。它调了终端工具，返回非零退出码。你以为是模型笨，把提示加长三倍，还是失败。
后来发现：命令在沙箱里根本没有pnpm。问题在执行环境，不在「想不想得清楚」。
工具失败常见混在一起。分层以后，动作才对得上病。
二、三层分别是什么
第一层：模型决策
模型有没有选对工具？参数意图对不对？该不该在缺信息时先搜索再写？
症状：调错工具、漏调、乱调、该停不停。
第二层：协议与参数
工具名、JSON 参数、必填字段、类型是否符合 schema？MCP / API 是否校验失败？
症状：参数缺失、类型错误、未知工具名、解析失败。
第三层：执行环境
权限、网络、路径、依赖、超时、沙箱策略、密钥是否可用？
症状：命令找不到、权限拒绝、连不上、超时、磁盘只读。
三、推荐排查顺序
（A）先看原始工具结果：退出码、stderr、HTTP 状态，不要只看模型转述
（B）确认工具名与参数是否合法（第二层）
（C）在同一环境手动复现命令（第三层）
（D）若环境与参数都对，再回头看提示与决策（第一层）
很多人颠倒：先改人格化提示，却不复现命令。
四、每层最小修复动作
第一层：补约束与验收；减少工具数量；要求「先只读探测」。
第二层：收紧 JSON Schema；给枚举；对失败返回可机读错误码。
第三层：装依赖、开放路径、延长超时、提供只读凭据、修好沙箱。
下面是一个更利于第二层排查的工具错误返回示意。
{"ok":false,"code":"ENOENT","tool":"run_terminal","message":"pnpm: command not found"}上面代码中，code与message让宿主和模型都能定位到环境层，而不是笼统的「失败了」。
五、和 MCP / 约束验收的关系
MCP 把工具接到宿主；接上不等于稳。Server 挂了、schema 漂移、权限过宽，都会在二三层爆雷。
「约束 + 验收」主要稳住第一层：少让模型在模糊目标下乱点工具。三层要一起看。
六、常见误区
（1）只骂模型
多数是环境与契约。
（2）吞掉 stderr
等于丢掉第三层证据。
（3）工具说明过长却缺必填示例
第二层更容易出错。
（4）一次给二十个高危工具
第一层选错概率上升。
七、小结与下一篇
工具失败，先问：决策错了、参数错了，还是环境执行错了？按层动手，比反复加形容词有效。
下一篇预告：上下文太长时，砍什么、留什么。
（完）
