过时的工具描述是 AI Agent 最大的隐形故障诱因

你交付了一个工具，让你的 Agent 可以获取用户个人资料。描述中写道：“通过用户 ID 检索用户信息。”六周后，后端团队将 user_id 重命名为 customer_uuid 并添加了一个必填的 tenant_id 字段。没有人更新工具的 Schema。你的 Agent 继续调用旧的签名，收到 400 错误，将空结果解释为“未找到用户”，并“热心地”创建了一个重复记录。

日志中没有错误。没有触发任何报警。Agent 全程都非常自信。

这就是工具文档问题：Schema 漂移将陈旧的描述变成了隐性故障向量。这可能是当今生产环境 AI 系统中最被低估的可靠性风险，而且你的 Agent 运行的时间越长，情况就越严重。

为什么工具描述不仅仅是文档

大多数工程师将工具描述视为注释——可选的，如果有帮助当然好，但并非关键的承重部分。这是一个错误。

当 LLM 调用工具时，它只有两个信号可以参考：Schema（参数名称和类型）和描述（解释工具功能以及如何调用的自然语言）。模型无法访问实现代码。它无法检查 user_id 是否最近被重命名。它无法知道上周二是否添加了一个新的必填字段。它完全是根据你提供给它的 Schema 进行推理。

这意味着工具描述在精确意义上就是 API 合约：它们是模型用来做出所有调用决策的规范。一项 2025 年的分析发现，97% 的工具描述至少包含一个质量问题——模糊的功能说明、缺失的参数格式、含糊的枚举值。当这些描述与实际实现发生偏离时，你就会面临双重失败：描述从一开始就不够精确，而现在它又是错误的。

危险不在于 Agent 抛出错误。危险在于 Agent 不抛错。它继续运行，返回看似合理的结果，直到最后有人注意到不对劲——通常是几周后，当损失已经成倍增加时，问题才会浮出水面。

Schema 漂移在实践中是如何发生的

其机制非常平凡，这也是问题得不到解决的部分原因。

后端工程师为了提高查询准确性添加了一个必填字段。该字段已记录在 API 变更日志中。但没有人把更新工具描述列入清单。Agent SDK 是独立部署的。模型 Prompt 中的描述仍然显示旧的内容。

或者是一个弃用周期（Deprecation Cycle）：旧参数名称在一段时间内仍然有效，因此集成测试通过了。等到旧名称不再被接受时，Agent 的故障模式已经从“错误结果”转变为“硬错误”——这至少是可见的，但在转变之前的静默期已经造成了实质性的损害。

一个相关的故障是保留语义但改变格式的字段重命名：user_id（整数）变为 customer_uuid（UUID 字符串）。Agent 仍然会为所谓的“用户标识符”发送一个值，但它发送的是一个整数。后端返回了错误记录的结果，或者根本没有结果，而 Agent 会围绕空响应进行推理，而不是将其标记为 Schema 错误。

不可见性是核心。与缺失的导入或错误的端点调用不同，Schema 漂移的执行过程非常顺畅，以至于 Agent 不会停止——它只是在错误的前提下以高度自信继续运行。

“文档即合约”的准则

解决方法不是写更好的描述。而是将描述变更视为破坏性的 API 变更——句号。

这意味着在你的工程流程中需要落实几件具体的事情：

描述变更需要经过与接口变更相同的审查关卡。 将“通过 ID 获取用户个人资料”修改为“返回旧版客户记录”的 PR，需要像修改签名一样接受严格审查。这种变更改变了模型用于决定何时以及如何调用工具的语义合约。

加载中…