3.2 工具 schema 也是上下文

3.2 工具 schema 也是上下文

本节摘要：常驻层的另一半是工具 schema——模型每轮都要逐字读的"API 文档"，却是最常被漏算的上下文：它由 API 自动注入，不出现在你拼的 prompt 字符串里，于是预算表忘了它、优化也轮不到它。本节先算清成本：单个 schema 约 100500 token，1540 个工具的常驻税可达 2k~10k token（示意），与系统提示同量级。再讲更关键的权衡：工具越多，选择越差——Anthropic 的建议是保持"能完成任务的最小工具集"（官方）；机制上，每个工具描述都在稀释其他工具的注意力，语义重叠的工具会互相诱骗。然后给工具描述的三层写法（是什么 / 何时用 / 何时别用）与参数、返回值、错误码的描述要点。最后是节税三招——精简合并、分阶段注入（工具路由）、子 Agent 隔离——附 ce_tools.py 成本核算示意，把工具集的常驻税变成账本上一行可审计的数字。

学习目标

阅读完本节，你应当能够：

1. 估算自己工具集的常驻税，并把它加进 2.1 节的预算分配表。
2. 说出"工具越多选择越差"的机制与三个失效信号。
3. 按三层写法重写一个工具描述。
4. 根据场景在三招节税手段中做选择。

一、被漏算的常驻项

一个测试：你的应用里，进入模型窗口的 token 都来自哪里？多数人的答案是"系统提示 + 用户消息 + 历史 + 检索"。漏了一项——工具 schema。只要请求带了 tools 参数，全部工具的名称、描述、参数说明就每轮自动注入，位置在系统提示附近，模型逐字读取。

它满足指令成分的三问（1.2 节）：开发者产生、每轮常驻、设计期裁剪——所以它是常驻税，而且是最隐蔽的一笔。量级（示意）：

# ce_tools.py —— 工具集常驻税核算（写法示意，以官方文档为准）
import json

def est_tokens(text: str) -> int:                      # 与 ce_budget.py 同口径
    cn = sum(1 for ch in text if "\u4e00" <= ch <= "\u9fff")
    return cn + (len(text) - cn) // 4

def tool_tax(tools: list[dict], window: int = 128_000) -> dict:
    """tools 为 function calling 风格的 schema 列表。返回常驻税与占比。"""
    cost = est_tokens(json.dumps(tools, ensure_ascii=False, indent=2))
    return {"tools": len(tools), "tokens": cost,
            "share_pct": round(100 * cost / window, 1)}
# 示例输出（示意）：15 个工具 → 3.1k token，占 128k 窗口的 2.4%
​

二、工具越多，选择越差

成本之外有第二重代价：选择质量随工具数下降。Anthropic 在其上下文工程长文中的建议是保持"能完成任务的最小工具集"——加载更多工具不是增强能力，而是降低可靠性（官方）。机制有二：

1. 注意力稀释不豁免工具：1.1 节的规律在工具区同样生效——40 个工具的描述互相稀释，每个工具分到的"被读到概率"变薄；
2. 语义重叠互相诱骗：search_orders、query_order、find_recent_orders 三个名字摆在一起，模型在错误的那个上纠结；参数相近时还会编造混搭的参数。

三个失效信号（见到先查工具集规模，再查 prompt）：

• 模型调用不存在的工具名，或把 A 工具的参数塞给 B；
• 在两个相近工具间反复横跳，一轮换一个；
• 明明有更顺的工具，模型偏用笨路径（用通用搜索找本可直查的数据）。

⚠️ "把 40 个工具都给它，让它自己选"是把路由问题甩给模型——模型会诚实地替你承受选择负担。工具集的裁剪是开发者的职责，不是模型的。

三、工具描述怎么写：三个层次

工具描述是写给模型读的 API 文档，分三层，一层比一层值钱：

第三层最值钱也最常缺——它直接对冲第二节的"语义重叠诱骗"。参数与返回值的要点：参数说明里给格式与示例（"日期格式 YYYY-MM-DD"胜过"传日期"）；返回结构说清字段含义（模型要基于它生成答案）；错误码必须描述（"404 表示订单不存在，应向用户核对单号而不是重试"）——错误描述写得好，模型能自纠错；写得差，它只会原地重试。

四、节税三招

工具集真的需要 40 个怎么办？三招按侵入性排序：

1. 精简合并（第一选择）：按"一个语义一个工具"合并——三个查单工具合成一个带过滤参数的；砍掉半年零调用的僵尸工具（调用统计在 API 日志里都有）。多数平台精简后能减三分之一（示意）。
2. 分阶段注入：按任务阶段切换工具集——退款流程只挂 5 个工具，售后咨询挂另外 8 个；模型先通过一个"目录工具"声明意图，应用层再注入对应子集。工程化做法见《Harness 工程》第 4.2 节的工具路由（纯文字互引，不在此展开）。
3. 子 Agent 隔离：把一组工具连任务一起外包给子 Agent——它在独立窗口里带着全套工具干活，只把结论摘要带回主窗口（官方，Anthropic 称其为上下文隔离的基本手段）。主窗口因此只付"任务描述 + 结果摘要"的价钱，而不付整组工具的常驻税。代价是多一次模型调用的延迟与成本，适合重而独立的工作块。

💡 三招不互斥，常见的成熟组合是"先精简合并打地基，再对高频重活用子 Agent 隔离，中间态场景按阶段切工具集"。选择依据回到 2.1 节的预算表：先算清每个方案省下的常驻税与付出的新增成本（子 Agent 的一轮调用、路由的一次判断），再动手。

本节要点回顾

1. 工具 schema 是指令成分：开发者产生、每轮常驻、设计期裁剪——最隐蔽的常驻税，量级与系统提示相当（示意 2k~10k）。
2. 工具越多选择越差（官方建议最小工具集）：注意力稀释 + 语义重叠诱骗；三个失效信号——错名混参、反复横跳、笨路径。
3. 描述三层写法：是什么 / 何时用 / 何时别用——第三层对冲重叠诱骗最值钱；错误码描述好了模型能自纠错。
4. 节税三招：精简合并（先做）、分阶段注入（路由）、子 Agent 隔离（独立窗口只回摘要）。
5. 审计习惯：ce_tools.py 的输出加进预算分配表，工具集变更如同系统提示变更一样走评审。
6. 路由与隔离有专门讲法：分阶段注入见《Harness 工程》第 4.2 节，子 Agent 架构在框架篇（第 7 章，后半）还会回来。

至此常驻层（指令 + 工具）完全定型——开发者写下的每一个字都过了审计。从下一章起进入动态层：先看记忆——那个系统在运行中自己长出来、必须在运行中自己管住的成分（第 4 章）。