给 Agent 返回错误时，别只写一个“失败”
文档工具只返回一个“失败”，Agent 就无法判断该修参数、等一会儿、查询结果，还是停止执行。错误应提供足够的信息帮助调用方选择恢复路径，同时明确这次操作是否可能已经产生副作用。
先区分协议错误与执行错误
MCP 工具规范区分协议层错误和工具执行错误。调用格式不符合协议，与工具运行后发现业务条件不满足，并不是同一种情况。执行错误可以通过工具结果的错误标识表达，让模型获得可处理的反馈；具体结构仍应与工具契约一致。
例如未知工具名属于调用层问题，找不到目标段落属于执行语义问题，网络中断则可能留下结果未知。把这些情况都包装成同一个状态码，会让自动恢复只能盲目重试，也让人工排查缺少入口。
错误结果至少帮助回答四个问题
| 问题 | 可提供的信息 |
|---|---|
| 哪里出了问题 | 阶段、对象与稳定错误类别 |
| 是否发生了修改 | 未执行、已执行或结果未知 |
| 能否重试 | 前提、建议间隔与操作键要求 |
| 怎样继续 | 可执行的下一步和查询入口 |
错误消息可以使用自然语言解释，但自动化逻辑应依赖稳定类别，而不是解析某句会变化的提示文本。类别需要足够具体以指导行动，也不必为每个内部异常都设计一种对外代码。原始堆栈可以留在受控日志中，用户结果保留必要线索。
可重试不等于立即再发一次
参数错误通常需要先修输入；服务限流可能要求等待；版本不匹配需要重新读取；写入响应超时则应先查询结果。HTTP 语义与具体接口规则都需要参考，不能仅凭“服务器错误”就认定重发不会造成重复文档。
尤其要避免把重试建议写成没有条件的布尔值。如果一次创建可能已经成功，应要求沿用原操作身份或进入对账流程。调用方收到错误之后，应该知道自己正在恢复原任务，还是发起一项新的业务动作。
让错误样本参与工具验收
测试非法字段、空目标、重复匹配、服务暂时不可用和响应丢失等情况。检查错误类别是否稳定、说明是否准确、恢复路径是否可执行，以及没有把未知状态伪装成确定失败。成功路径可用，不代表工具已经适合无人值守运行。
还要检查错误信息是否意外包含密钥、整段私密文档或无关个人信息。诊断需要的是对象定位与必要上下文，不是把所有原始输入原封不动回显。足够具体和适度收敛可以同时实现。
好的错误契约能让 Agent 和人工接手者做出同样合理的下一步判断。它不是给失败换一个更长的文案，而是把状态、证据和恢复方式组织成可执行的信息。
在企业文档中验证
如果要把本文方法用于企业文档，可预约演示，结合实际资料核对协作、权限与集成方式。
需要在自己的环境中验证时，可先了解私有化部署方案，再确定试用范围与验收要求。