源码里的 ToolNotFoundError 抛两种消息，看有没有冒号后半句就能分开：
| 报错原文 | 含义 | 该查哪 |
|---|---|---|
unknown tool "<name>" | 这个名字哪里都没注册 | 网关是否改了工具名、截断了名字，或中间层重写了工具调用 |
unknown tool "<name>": <reachableFrom> | 名字可见但呈现层不允许直接调用 | 别查网关。查 DSH_TOOLS_MODE 与preset的tool-presentation |
第二种最容易被误判
它的典型场景是PTC模式：模型只被允许直接调 run_code，其它native工具名虽然可见，直接调用就会被拒，并附带「你该从哪调用它」的说明。这跟网关一点关系都没有，但报错文本长得很像协议错误，很多人第一反应是去查网关。
怎么一次定位
- 看后半句。有
: …就跳到「呈现层」分支，直接停手别查网关。 - 没有后半句，抓一次出站请求体，把
tools[].function.name与本地注册的名字逐个比对。 - 两边一致还报UNKNOWN_TOOL → 本地侧问题；不一致 → 网关或中间层改写了名字。
这个错误码的设计其实是好的：它继承自HarnessError，让「工具不存在」和「工具执行失败」在重试/沙箱/回放逻辑里可区分。可惜它的两种消息只差一个冒号，读快了就会错过。