夜雨聆风
系列：AI Agent 架构设计（二十一）：工具返回值设计——返回太长上下文变脏，返回太短模型看不懂
目标：工具返回了什么，和工具能做什么一样重要——返回值设计是 Agent 上下文污染最常见的来源
适合：对 Agent 底层设计感兴趣，想真正理解"为什么这样设计"的读者
预计阅读：15 分钟
工具执行完了，麻烦才刚开始
工具调用成功了，返回了结果。
但这个结果现在要进入上下文。从这一刻起，它会占据上下文里的一块空间，在后续所有推理里被模型"看到"——直到这个 Session 结束，或者被 Compaction 压缩掉。
如果返回值设计得不好，它会持续地污染后续的推理：
返回太长：5 万字的日志全量注入上下文，关键信息被淹没，Lost in the Middle 问题加剧，Token 成本暴涨，后续每次调用都带着这 5 万字作为"包袱"。
返回太短：只返回"成功"或者一个 ID，模型不知道接下来该怎么做，下一步推理质量下降，甚至会再次调用工具来获取本来应该一起返回的信息。
返回格式不对：模型对 JSON、XML、Markdown 的处理能力不同。格式不对，模型理解效率低，也可能产生解析错误。
错误消息太抽象：工具失败了，只返回"Error 500"，模型不知道原因，不知道怎么修，可能会盲目重试或者换一个错误的方向继续。
返回值设计，是工具设计里最容易被忽视、但影响最持久的部分。
Anthropic 的官方建议：25,000 Token 上限
Anthropic 在工具设计指南里给出了明确的数字：
Claude Code 默认把工具返回值限制在 25,000 Token 以内。
这不是随意设定的数字。Anthropic 的理由是：
"优化上下文质量很重要，但优化工具返回给 Agent 的上下文数量同样重要。我们建议对任何可能消耗大量上下文的工具返回值，实现分页、范围选择、过滤、截断的某种组合，并设置合理的默认参数。"
25,000 Token 大约是 2 万字——够模型做出合理判断的信息量，但不会撑爆上下文。
重要的是：这个限制预计会随着上下文窗口的增大而调整，但"需要上下文高效的工具"这个需求不会消失。 上下文窗口扩大，不是"可以随便返回大量数据"的理由，而是"可以处理更复杂任务"的能力扩展。
错误返回值：比成功返回值更重要
工具失败了，返回的错误消息是模型决策的唯一依据。
一个真实的案例：Anthropic 发布 Claude 的网页搜索工具时，发现模型会在搜索查询里无缘无故加上"2025"，导致搜索结果出现年份偏差。修复方法不是改模型，而是改工具描述——在描述里明确说明"不要在查询里添加年份约束，除非用户明确要求"。
这说明工具的返回值和描述，会系统性地塑造模型的行为。 一个工具的设计问题，会在每次调用这个工具的任务里反复出现。
三个框架对返回值设计的不同态度
Claude Code：50K 外部化是架构级保护
Claude Code 对超长返回值有一个框架级别的保护机制：
当工具调用返回内容超过 50,000 字符，自动触发外部化——完整内容写入临时文件，上下文里只注入约 2KB 的摘要和文件引用。模型需要更多细节时，通过文件读取工具按需获取。
工具返回 100,000 字符的日志 ↓超过 50,000 字符阈值 ↓完整内容写入 /tmp/tool_output_xxx.txt ↓上下文注入："工具返回了大量输出，已保存到 tool_output_xxx.txt。摘要：发现 127 条 ERROR 级别日志，主要集中在 14:30-15:00。如需查看完整输出，使用 read_file 工具读取文件。"
这个机制保护了主上下文不被单次工具调用撑爆，同时给了模型继续工作的信息（摘要）和获取更多信息的路径（文件引用）。
OpenClaw：无架构级保护，依赖 Skill 作者
OpenClaw 没有类似 Claude Code 的 50K 外部化机制。
工具返回什么、返回多少，完全由 Skill 作者决定。如果 Skill 作者没有实现分页和截断，工具可能返回几十万字的原始内容，全部注入上下文，没有任何自动保护。
ClawHub 上工具返回值设计的质量参差不齐。有质量好的 Skill，会在工具描述里明确说明返回值大小限制和分页参数；也有质量差的 Skill，直接暴露底层 API 的原始输出，没有任何裁剪。
Hermes：内置工具设计合理，execute_code 是特殊路径
Hermes 的 40+ 内置工具，大多数遵循了合理的返回值设计：有限制最大返回量、支持分页参数、错误消息有基本的可读性。
Hermes 最有特色的是 execute_code 工具——模型可以写脚本来处理数据，脚本的输出作为工具返回值。
原始日志可能有 10 万行，但脚本只返回了几十个 Token 的摘要。 模型"看到"的是处理结果，不是原始数据。这本质上是把"数据处理"放在了工具里，而不是让模型来处理原始数据。
这也是 Hermes 处理长文档的推荐方式（第二十七篇讲过的）：对于结构化数据，让 execute_code 处理，返回摘要；对于非结构化内容，才考虑直接读取。
返回值是工具和模型之间的对话
工具的返回值，不只是"给了模型一个结果"。它是工具在告诉模型：
"发生了什么"——操作的结果。
"还有什么可以做"——分页提示、相关工具建议。
"如果出错了，下一步怎么办"——可操作的错误说明。
设计得好的返回值，让模型每次读完都知道接下来该做什么。设计得差的返回值，让模型每次都要在大量噪音里找信号，或者因为信息不足而做出错误决策。
Anthropic 在指南里说的那句话，在返回值设计这里同样适用：
"工具设计和 prompt 工程一样，需要同等程度的投入。"
工具能调出什么，往往被高估。工具返回什么、怎么返回，往往被低估。但后者对 Agent 稳定性的影响，一点都不亚于前者。
系列：AI Agent 架构设计（二十一）：工具返回值设计——返回太长上下文变脏，返回太短模型看不懂
目标：工具返回了什么，和工具能做什么一样重要——返回值设计是 Agent 上下文污染最常见的来源
适合：对 Agent 底层设计感兴趣，想真正理解"为什么这样设计"的读者
预计阅读：15 分钟
系列：AI Agent 架构设计（二十一）：工具返回值设计——返回太长上下文变脏，返回太短模型看不懂
目标：工具返回了什么，和工具能做什么一样重要——返回值设计是 Agent 上下文污染最常见的来源
适合：对 Agent 底层设计感兴趣，想真正理解"为什么这样设计"的读者
预计阅读：15 分钟
工具执行完了，麻烦才刚开始
工具调用成功了，返回了结果。
但这个结果现在要进入上下文。从这一刻起，它会占据上下文里的一块空间，在后续所有推理里被模型"看到"——直到这个 Session 结束，或者被 Compaction 压缩掉。
如果返回值设计得不好，它会持续地污染后续的推理：
返回太长：5 万字的日志全量注入上下文，关键信息被淹没，Lost in the Middle 问题加剧，Token 成本暴涨，后续每次调用都带着这 5 万字作为"包袱"。
返回太短：只返回"成功"或者一个 ID，模型不知道接下来该怎么做，下一步推理质量下降，甚至会再次调用工具来获取本来应该一起返回的信息。
返回格式不对：模型对 JSON、XML、Markdown 的处理能力不同。格式不对，模型理解效率低，也可能产生解析错误。
错误消息太抽象：工具失败了，只返回"Error 500"，模型不知道原因，不知道怎么修，可能会盲目重试或者换一个错误的方向继续。
返回值设计，是工具设计里最容易被忽视、但影响最持久的部分。
Anthropic 的官方建议：25,000 Token 上限
Anthropic 在工具设计指南里给出了明确的数字：
Claude Code 默认把工具返回值限制在 25,000 Token 以内。
这不是随意设定的数字。Anthropic 的理由是：
"优化上下文质量很重要，但优化工具返回给 Agent 的上下文数量同样重要。我们建议对任何可能消耗大量上下文的工具返回值，实现分页、范围选择、过滤、截断的某种组合，并设置合理的默认参数。"
25,000 Token 大约是 2 万字——够模型做出合理判断的信息量，但不会撑爆上下文。
重要的是：这个限制预计会随着上下文窗口的增大而调整，但"需要上下文高效的工具"这个需求不会消失。 上下文窗口扩大，不是"可以随便返回大量数据"的理由，而是"可以处理更复杂任务"的能力扩展。
错误返回值：比成功返回值更重要
工具失败了，返回的错误消息是模型决策的唯一依据。
一个真实的案例：Anthropic 发布 Claude 的网页搜索工具时，发现模型会在搜索查询里无缘无故加上"2025"，导致搜索结果出现年份偏差。修复方法不是改模型，而是改工具描述——在描述里明确说明"不要在查询里添加年份约束，除非用户明确要求"。
这说明工具的返回值和描述，会系统性地塑造模型的行为。 一个工具的设计问题，会在每次调用这个工具的任务里反复出现。
三个框架对返回值设计的不同态度
Claude Code：50K 外部化是架构级保护
Claude Code 对超长返回值有一个框架级别的保护机制：
当工具调用返回内容超过 50,000 字符，自动触发外部化——完整内容写入临时文件，上下文里只注入约 2KB 的摘要和文件引用。模型需要更多细节时，通过文件读取工具按需获取。
工具返回 100,000 字符的日志↓超过 50,000 字符阈值↓完整内容写入 /tmp/tool_output_xxx.txt↓上下文注入："工具返回了大量输出，已保存到 tool_output_xxx.txt。摘要：发现 127 条 ERROR 级别日志，主要集中在 14:30-15:00。如需查看完整输出，使用 read_file 工具读取文件。"
这个机制保护了主上下文不被单次工具调用撑爆，同时给了模型继续工作的信息（摘要）和获取更多信息的路径（文件引用）。
OpenClaw：无架构级保护，依赖 Skill 作者
OpenClaw 没有类似 Claude Code 的 50K 外部化机制。
工具返回什么、返回多少，完全由 Skill 作者决定。如果 Skill 作者没有实现分页和截断，工具可能返回几十万字的原始内容，全部注入上下文，没有任何自动保护。
ClawHub 上工具返回值设计的质量参差不齐。有质量好的 Skill，会在工具描述里明确说明返回值大小限制和分页参数；也有质量差的 Skill，直接暴露底层 API 的原始输出，没有任何裁剪。
Hermes：内置工具设计合理，execute_code 是特殊路径
Hermes 的 40+ 内置工具，大多数遵循了合理的返回值设计：有限制最大返回量、支持分页参数、错误消息有基本的可读性。
Hermes 最有特色的是 execute_code 工具——模型可以写脚本来处理数据，脚本的输出作为工具返回值。
原始日志可能有 10 万行，但脚本只返回了几十个 Token 的摘要。 模型"看到"的是处理结果，不是原始数据。这本质上是把"数据处理"放在了工具里，而不是让模型来处理原始数据。
这也是 Hermes 处理长文档的推荐方式（第二十七篇讲过的）：对于结构化数据，让 execute_code 处理，返回摘要；对于非结构化内容，才考虑直接读取。
返回值是工具和模型之间的对话
工具的返回值，不只是"给了模型一个结果"。它是工具在告诉模型：
"发生了什么"——操作的结果。
"还有什么可以做"——分页提示、相关工具建议。
"如果出错了，下一步怎么办"——可操作的错误说明。
设计得好的返回值，让模型每次读完都知道接下来该做什么。设计得差的返回值，让模型每次都要在大量噪音里找信号，或者因为信息不足而做出错误决策。
Anthropic 在指南里说的那句话，在返回值设计这里同样适用：
"工具设计和 prompt 工程一样，需要同等程度的投入。"
工具能调出什么，往往被高估。工具返回什么、怎么返回，往往被低估。但后者对 Agent 稳定性的影响，一点都不亚于前者。
