给 Agent 加工具调用之前，先把失败路径设计好

演示教程：面向工具调用的工程设计清单，供你参考写作结构。

工具不是总会成功

网络超时、参数错误、资源不存在都应成为显式结果。把可重试错误与不可重试错误分开，避免模型一遍遍重复同一个失败动作。

明确输入与执行边界

工具参数通过 schema 校验。为查询和写操作设置不同权限，写操作提供幂等键与审计标识。重试上限、总时长和预算由服务端约束。

type ToolResult =
  | { ok: true; data: unknown }
  | { ok: false; retryable: boolean; message: string };

建立失败回归集

为无效参数、超时、重复请求、权限不足各留一个用例。每次更新模型或工具说明后重跑，检查 Agent 是否能给出可理解的失败解释。