← Context From First Principles

工具产出上下文

工具两独立治理的面分开算账:调用前占上下文的能力表示,调用后成候选信息的结果,省两边上下文丢什么都要测。

这里是个说明 case。智能体接十五个集成开常规任务:文件工具、shell、搜索、web、数据库、issue 跟踪、聊天、日历、网盘、部署、监控。假设 harness 把可能永远不调的操作的描述也暴露了,项目文件还没读。然后跑一次搜索,运行时为十几行答得了的问题准入很大的匹配列表。工具调用前收一次上下文预算,调用后又收一次。

标题是简称。工具产出潜在上下文,即候选信息,上下文只在运行时准入后存在:

工具输出 ≠ 上下文

本章两边收费分开算,问省上下文的每机制丢什么。不拥有 general 准入([第 14 章](/zh-cn/books/context/14-chapter/))和 general 表示([第 18 章](/zh-cn/books/context/18-chapter/))。权威性新鲜度范围归第 19–21 章。

两面

能力面是可执行可能的模型可见表示:名字、描述、输入 schema,暴露处还有输出 schema、注解、例子、服务器指令。不是每运行时暴露每元素。观察面是执行结果的表示,错误、结构化输出、引用、日志、metadata,运行时最终让模型可见。raw 工具结果还不是那个面;生产者 shaping 与消费者准入决定什么到达它。每面有自己的流水线,每箭头都能坏:

能力侧
运行时能力 universe → 能力候选 → 暴露
  → 模型可见能力 → 模型选择 → 调用

执行侧
调用 → raw 结果 → 生产者侧 shaping → 观察候选
  → 消费者准入 → 模型可见观察 → 行为

law 跟阶段走:

工具有  ≠  工具暴露  ≠  工具选中  ≠  工具执行
工具调用发出  ≠  观察拿到
raw 结果  ≠  观察候选  ≠  准入观察
工具返回 x  ≠  模型观测 x

末条用[第 13 章](/zh-cn/books/context/13-chapter/)的边界:运行时过滤截断引用结果再准入,后面的模型调用不能 credit 没在它捕获输入里的细节。观察器确立边界层 absence,不确立捕获外 provider 可能供给的一切。

常驻能力代价

能力暴露是运行时能力的表示为当前算子提供给模型。运行时能有一百工具、暴露八个,运行时可用的工具不是暴露给模型的工具。常驻能力代价是暴露的能力表示的模型输入成本,那次调用执行否都算。provider 缓存改变处理计费,不改变 token 占用,所以常驻 token 占用 ≠ 常驻计费成本([第 9 章](/zh-cn/books/context/09-chapter/))。

工具数不是能力代价:

工具数  ≠  能力面尺寸  ≠  能力 ambiguity

十个 well-separated 的工具能比三个 overloaded 的容易。schema token 也不是浪费,更丰富的 schema 防 invalid 调用重试修复提示,定义最小化 ≠ 轨迹最小化。例子是能力表示的一部分,成分(名字描述 schema 例子注解)运行时暴露处分开测。

执行侧成本也不是一数。它含调用的表示、准入的观察、输出不够的后续调用、恢复继续、错 invalid 调用的修复。工具算子上贵、上下文便宜也可能,反过来也可能,所以工具执行成本 ≠ 工具上下文成本。正确的核算 horizon 是整轨迹,每出现计数一次,工具执行收费和模型上下文占用分开。下面示意列类别,不是 provider 计费方程:

轨迹工具上下文成本 = 能力占用 + 调用表示
    + 准入观察 + 恢复继续 + 修复互动

缓存计费分开观测,部署不定标量就不定义综合标量。轨迹评估和阶段归因都要。

工具数 degrade 能力

Paramanayakam 等(2025)证明量化的 Llama 3.1 8B 在 46 工具定义的 GeoEngine benchmark 任务挂、只给 19 个过,原上下文装进模型 advertised 窗口。这是特定模型 benchmark 例子,不是 19 或 46 工具的 general 阈值。失败不是溢出问题;是上下文混淆([第 5 章](/zh-cn/books/context/05-chapter/))。Berkeley Function-Calling Leaderboard 记录复杂度不同的函数调用任务上模型性能差,含多调用并行调用、无关检测。这些对比 motivate 调查工具选择失败,本身 isolate 不了暴露额外工具定义的因果 effect。报道的例子 motivate 一个假设,不是 isolate 一般原因:暴露的工具定义在任何调用前就占上下文,减少暴露集可能帮也可能伤工具使用。只有等价可执行能力的受控对比才能 isolate 暴露的 effect。Breunig(2025)的后续文章把动态选相关工具的做法命名 tool loadout——智能体能访问一百工具,不必每调用暴露一百定义。这是值得测的实现模式,本章不定模型工具选择器,先测简单确定性选择政策。

等价能力,不同表示

find_user、find_project、find_issue 两套件和 search(resource_type, query) 暴露的底层操作等价否未定。不等价,工具结构和能力覆盖 confounded。问题不是多工具对少工具。而是:可执行能力等价,给定能力模型可见分解怎么影响常驻成本、选择、参数构造、轨迹成本?search_files、find_files、grep_files 之类的名字重叠是可能 ambiguity 的说明,名字像没测就是 demonstrated 混淆。Anthropic 报告前缀后缀命名空间选择对工具使用评估 effect 非 trivial,随模型变。那是它测试模型任务的厂商报告证据,没说明命名空间解决 ambiguity。

能力发现是从更大 universe 选哪些能力表示模型可见。它是能力侧 analogue 的[第 14 章](/zh-cn/books/context/14-chapter/)准入,失败一样:

能力暴露 miss ≠ 工具选择失败

模型选的工具调用下,模型直接选不了模型可见定义 withheld 的能力。运行时还能替模型执行隐藏能力,暴露不等于可执行可用。发现还有停止问题:暴露集看起来够了,不说明没披露的能力不会更好。Anthropic 的 Tool Search Tool 推迟大半定义,几个工具常载。那是一实现政策,pin 关键工具不是通用 law。工具块的动态变化移动渲染请求的第一分歧。provider 复用少了是独立观测,要缓存 telemetry。MCP 草案 spec 说服务器按确定性顺序返回工具,说 clients 缓存列表、工具在模型上下文时提高提示词缓存命中。那是带显式理由的 SHOULD。

生产者 shaping 与消费者准入

raw 响应是机器数据结构,不是上下文政策。两决定作用它:

生产者侧 shaping ≠ 消费者侧准入

生产者侧 shaping 在终观察候选拿去准入前发生;不等于没有中间候选 raw 结果:查询过滤、聚合、字段选择、分页、有界摘录、结构化投影、引用生成。第 14 章拥有产出候选的准入。操作互不相同:过滤 ≠ 摘要 ≠ 分页 ≠ 引用 ≠ 截断。过滤按指定标准选字段条目,摘要变换表示,分页跨请求控制范围,引用指向带恢复契约的 payload,截断机械界外丢内容。这些操作能组合,完整性来源 effect 独立记录。“简洁"藏了发生哪个。

shaping 本身能有损:

生产者侧 reduction ≠ 安全 reduction

输出少了不等于要求的信息留存([第 11 章](/zh-cn/books/context/11-chapter/))。确定性代码能稳定错,确定性 ≠ 正确。算子正确指定处,模型上下文外算子减少中间模型可见 state 和重复智能体调用,中间步骤不单独准入就模型不可见。它们只在运行时真记录(identity 输入错误信息够)才可审计。Anthropic 的代码执行文章用代码过滤万行表格(模型看到前)说明模式,报告工具定义按需加载 150,000 token 到 2,000 token 的 reduction。consolidated 工具藏中间决定、失败点、部分结果,留外部执行轨迹是独立设计选择。模型可见步骤少本身没确立操作更好。

厂商工具设计指南推荐高信号响应加 verbosity control,举例详细约 206 token、简洁约 72。建议分页、范围选择、过滤、截断组合加 sensible 默认,注 Claude Code 默认 25,000 token 响应上限,说 JSON XML Markdown 格式无 universally 赢。末点是[第 18 章](/zh-cn/books/context/18-chapter/)的。

完整性

观察除内容带完整性状态。概念上结果记录成功报错等结果,覆盖属性(完整、过滤、分页、截断、只有引用)另算。这些不是互斥 state:过滤响应能同时分页,报错伴随部分输出也行。这些是实验 states 不是生产 enum,“完整"指查询投影分页时间来源契约下的完整,不是世界的完整描述:

协议完整  ≠  世界完整

页不是完整结果。分页是继续契约,显式不完整,给请求另一范围的办法,继续可用 ≠ 继续执行。那又是[第 14 章](/zh-cn/books/context/14-chapter/)的停止问题。静默截断让省略的条目读成缺席,截断结果该说哪截、怎么继续。最强的后果:

没观测 ≠ 不在,空结果没完整性契约不等于缺席

“No matches” 取决于查询范围、权限、分页、过滤、截断、来源新鲜度。空结果只在声明的查询完整性契约里支撑阴性结论。返回的引用不是 artefact 读,bare opaque 指针语义信息太少,知情扩展决定做不了。带恢复引用的驻留语义 cue 加完整性状态是更好的形状,按第 12、13 章。

错误是观察。错误能带 decisive 事实,actionable 不完整:短消息漏掉修复要的细节。MCP 草案分协议错误(未知工具、畸形请求,模型大概率修不了)和标 isError 的工具执行错误(clients 该给模型自纠)。修错误 payload 减少意外暴露内部,也是,安全这里不测。

门与 metadata

能力可用、模型可见表示、执行许可、执行、结果准入逻辑上不同决定,运行时合其中几个也一样。OpenCode 的文档描述内置自定义 MCP 工具的允许拒绝询问 wildcards 许可模型,许可不是暴露准入:可用能力 ≠ 允许执行,允许 ≠ 要求暴露,暴露 ≠ 执行。定义驻留的拒绝工具还收常驻成本。

MCP 注解是 metadata 不是权威性。spec 把工具注解当不可信(来源可信除外);可信注解也是关于意图行为的断言,不是无害执行的证明。声明的只读能力还要适用执行政策,后果重要处验证。工具描述 inform 能力选择;工具结果是低信任来源内容。工具返回的祈使文本是待评估的数据,不是返回就获得权威性的指令,metadata 独立赋予管束权威([第 19 章](/zh-cn/books/context/19-chapter/))。工具够得着 x 不让 x 进任务范围([第 21 章](/zh-cn/books/context/21-chapter/))。

两 identity 对后面重要。同样工具同样参数不一定返回同样观察,世界 state 变。这就是 DCP 同工具同参数去重是实现政策、不是冗余证明的原因。旧失败调用的输入不因插件 purge 它的规则证明无关。DCP 把工具输出失败调用输入当 reduction 目标,留重复调用的最新,horizon 后 purge 失败调用输入、保留消息,保护一些工具,占位符历史不动,文档写缓存 trade-off。实现不是验证,它在准入后剪枝,本章在之前 shaping。

依赖

resolve 引用要模型选的工具调用,resolver 能力须暴露给模型并允许执行;运行时控制的 resolver 只须运行时可用。工具 mediated 信息因此带能力依赖,条目 token 不是依赖闭包准入成本。增量只在 resolver 额外准入时计数:20 token 引用加 650 token resolver 定义额外暴露就加 670 输入 token 位置,定义已驻留就加 20。这些数描述边际输入占用,不描述计费或 resolve 引用的全成本。定价 close 依赖归[第 23 章](/zh-cn/books/context/23-chapter/),运行时自动 resolve 引用就没有依赖。

证据

这些是工程例子与 spec。本书 workload 上一个没收集。

来源 证据类型 验证的断言 本章用 没确立
Anthropic,“Introducing advanced tool use”(2025 年 11 月 24 日) 厂商工程报告 五服务器 58 工具,定义 token 约 55K,Jira 一家约 17K,内部优化前 134K;Tool Search Tool 约 72K 到 8.7K,精度 49% 到 74%(Opus 4)、79.5% 到 88.1%(Opus 4.5);例子复杂参数精度 72% 到 90%;编程调用平均 token reduction 37%;少于十工具别 defer 的建议 大能力面存在,动态暴露改变那些系统的 token 使用 别的 workload 的 prevalence;general 精度 effect
Anthropic,“Writing effective tools for agents” 厂商工程报告 命名空间 effect 随模型变;verbosity control;25,000 token Claude Code 响应上限;actionable 错误 工具响应是上下文设计 任何指南最优
Anthropic,“Code execution with MCP” 厂商工程报告 结果进模型前代码过滤;按需工具定义(150K 到 2K token) 生产者侧 shaping 当模式 任何 reduction 安全
MCP 草案 spec 协议 spec 工具模型控制;确定性顺序是带缓存理由的 SHOULD;注解当不可信;两类错误 协议确切措辞 行为任何
OpenCode 工具文档 实现文档 13 内置工具加自定义 MCP 工具;允许拒绝询问 wildcards 许可 许可当独立门 测得的行为
DCP 第三方实现 去重、错误输入 purge、受保护工具、占位符、缓存注 工具输出是实践 reduction 目标 它的 reduction 安全

在 Context Viewer 里检查

本章的 viewer scene 用工具细节复用批准核算:调用前站十二定义,执行时调用表示,之后集中的观察。打开 scene 对比能力面观察面。看什么:双边收费——定义用前花钱,结果用后花钱——最大结果的集中。尺寸只是占用;大结果能带 decisive 事实。

一次捕获调用以工具为中心的堆叠成分。工具结果主导约 65%;定义调用各约 6%;推理约 12%。
一次捕获调用的工具能力观察 share。记录例子;只描述这次捕获。

在 Context Viewer 里打开工具 footprint scene

观察器

观察器在宿主模型-上下文 hook 记录每工具的名字描述输入 schema,每观测模型请求。注解不记,不是 provider 线路观测。工具定义的报告 token 取决于捕获表示与估计器,不是直接 provider token 归因。校准会话是 deliberate 测试,任何语料排除,仪器对本章 prevalence 断言没有 enroll 的 genuine 会话语料:

可观测 ≠ 观测到

真实上下文多少去定义,这里什么都没测量,没有一句说 OpenCode 花测得的 share。仪器能力不是生态证据。

提议的实验

这里什么都没跑。两面独立失败,分开测,真实会话语料是空的。

**生态门。**能力侧:可用暴露的工具,能力 token,稳定变化的定义,从没选中执行的暴露工具,动态发现频率,发现 miss(可观测处),schema 例子 token share。观察侧:raw 准入结果尺寸分布,过滤分页引用 frequency,错误结果尺寸,重复输出,继续调用,现行上下文 share。动态发现前,问真实会话是不是常驻定义主导。结果 shaping 前,问是不是超大输出主导:

机制省 token ≠ 它针对 prevalent 代价

**实验 A:能力面。**可执行操作权限等价,暴露与模型可见表示怎么影响工具选择、执行成功、轨迹成本?冻结:任务、后端操作语义输出、模型、解码、许可 state、非工具上下文、目标。工具定义可见性每调用记录;可组合工具条件的能力覆盖须检查不能 assumed。条件:oracle 能力集(hindsight,非生产),声明标准下可接受充分集之一;很多窄能力;同样加 plausible 无关;可执行后端语义等价的更少可组合能力;小面动态发现;可选 deliberate ambiguous 套件当诊断;需要处最小丰富 schema ablation。失败按最早确立的阶段归因:运行时能力没有、要求的能力没暴露、暴露的工具选错、参数畸形错误、执行失败、观察没准入、下游使用失败。缺失工具调用 alone 分不清暴露 miss 和 deliberate 不选。指标:每可接受能力路径可用暴露否,选择 valid 调用率,冗余修复调用,任务成功,能力 token,发现开销,延迟,全轨迹 token,provider 缓存指标(有处)。报告候选集覆盖与精确渲染定义,不只工具数。算数的结果:全工具暴露打平 oracle,无关工具什么都不改变,可组合工具省定义 token 但 invalid 调用涨,发现省 token 但暴露 miss,发现打平全暴露还省 token,丰富 schema 回本 token,尺寸 ambiguity control 后工具数什么都不预测。

**实验 B:观察面。**同样底层数据,生产者侧 shaping 怎么影响信息留存、行为、继续、轨迹成本?冻结:工具、源数据、查询任务、模型、解码、当前上下文、相关处准入预算、要求事实标识符、oracle 答案。主要对比消费者准入规则冻结,同样预算尝试准入提供的观察;拒绝截断记成准入结果,不归因 shaping。单独 factorial 对比变准入。raw 结果、shaping 候选、真准入尺寸独立测。条件:raw 完整;确定性过滤投影;带显式继续契约分页;带 durable 恢复引用的有界语义 cue;带截断 marker 显式截断;fixture specific oracle 观察。cue 须冻结,生成成本状态保留检查和确定性过滤分开记录。表示形式归[第 18 章](/zh-cn/books/context/18-chapter/)。hazard fixture 带陷阱:尾部关键条目;大无关 bulk;有损 shaping 满足不了的精确标识符;阴性证据(正确答案取决于知道完整搜索什么都没找到);修复要容易省略细节的错误(错误 shaping 这里测,不开第三实验);扩展 hold decisive 细节的引用。度量分开:raw、候选、准入、引用、重引入 token;要求事实、精确值、来源、完整性契约留存;任务成功、后续正确、false 阴性决定、不支持的断言;调用、继续、扩展、延迟、total token。算数的结果:raw 打平 shaping(代价可接受);过滤省 token 丢 decisive 事实;分页导致过早停止;显式截断 marker 还产出 false 缺席断言;引用省 token 扩展吃掉省的;紧凑结果改变精确值;确定性投影打平 oracle;错误 shaping 删掉修复关键证据。

**Falsifier。**测试条件下全暴露 comparable 总成本下表现一样,动态发现 unjustified;发现 miss 要求的能力,或发现开销超省的占用。单测得的选择干扰 absence 不证伪纯成本 benefit。aggressive 生产者 shaping 在测试契约下丢要求证据或触发 false 缺席结论就拒绝。机制保留要求义务行为、测得整轨迹成本降,挣到条件支撑。那发现适用测试 workload provider 设置,不自动到别的工具环境。

交接

工具系统省上下文,要么删掉不需要的信息,要么把需要的信息移到另一能坏的决定后面。动态发现、分页、引用、过滤、截断各制造须测量的访问停止失败。第 17 章定哪些能力信息模型可见,执行怎么跨进候选信息。第 18 章问剩下 open 的问题:该模型可见的信息取什么表示?

参考