用颗粒度、描述与失败语义设计 Agent 工具

一句话提醒

工具调用质量不只看模型：工具边界、适用条件和无效结果后的行为都必须可定义、可验证。

为什么今天看它

• 很多 Agent 问题不是接口没接上，而是空结果或错误参数被模型当成正常信息继续推理。先把软失败定义清楚，才能把不稳定变成可验收的产品问题。

留一个问题

你正在设计或评审的一个 Agent 工具，是否能明确说出它不该何时调用，以及空结果、超时和参数错误后 Agent 应如何对用户可见地处理？

参考思路

1. 1.把工具收敛为一个原子、可验证且副作用清晰的任务。
2. 2.说明它做什么、何时适用、何时明确不适用。
3. 3.规定输入限制、返回值含义与可判定的成功条件。
4. 4.区分硬失败、软失败与幻觉调用，禁止把无效结果默认为成功。
5. 5.为每种失败定义重试、降级、转人工或告知用户的后续动作。

03_知识库/综合/Agent工具设计三要素：颗粒度、描述与失败语义.md