# 巨型对原子：工具粒度税六栈实测 ## 概述 工具表面怎么切，是 2026 年 Agent 工程里被两句口号绑架最深的伪命题。一派喊"工具越少越好，模型不懵"，另一派喊"每个操作都暴露成工具，模型自由组合"。AgentDoc 在一个 MCP 驱动的文档编辑器里跑了 **20 种工作流配置 × 13 个基准场景**，给出的实测结论很反直觉：巨型单工具 token 最省，但多步任务准确率是原子工具的 **3 倍差**；纯原子工具准确率拉满却在 **25 个工具**附近撞上悬崖，模型在 `insert_paragraph` / `insert_text` / `append_text` 这类近义词之间反复误选。真正的甜点既不是一极也不是另一极，而是"原子基座 + 3–5 个用自然语言命名的宏"——宏叫 `composeFormatBatch` 会被模型无视，叫 `replace_all` 会被立刻正确使用。本期拆解这条工具粒度的 U 型税曲线，并给出六栈通用的设计原则。 ## 多维度对比：三种工具粒度 | 维度 | 巨型单工具（monolithic） | 纯原子工具（atomic） | 混合：原子 + 命名宏 | |------|--------------------------|----------------------|----------------------| | Token 消耗 | 最低（一次大调用） | 最高（多轮往返膨胀） | 中等（宏砍掉 4→1 往返） | | 多步任务准确率 | 约为原子的 1/3（Levenshtein 3× 差） | 最高（可逐步验证） | 最高且 token 更省 | | 失败模式 | index drift、整篇文档腐化 | 25 工具悬崖、近义误选 | 宏命名错则被忽略，回退原子 | | 循环步数 | 1 步（无中间验证窗口） | 4+ 步（每步一次往返） | 1–2 步（宏压缩高频路径） | | 状态敏感操作 | 几乎必崩（一次前向 pass 规划全部变更） | 稳（每步可重读） | 最稳（宏内封验证） | | 变现包装度 | 低（演示型，崩了难救） | 中（教 ReAct 循环好素材） | 高（最像真实生产，可做训练营主线） | ## 深度分析 ### 一、巨型单工具：token 最省，准确率 3 倍差 巨型单工具的诱惑是显而易见的——把 `edit_document` 做成一个接收大 payload 的工具，模型一次性吐出整段变更，循环步数压到 1，token 账面最漂亮。AgentDoc 的实测里，它的 token 消耗在所有配置里垫底，是基准里"最便宜"的一个。但代价藏在准确率里：在多步任务上，它的 Levenshtein 编辑距离（最终文档与目标文档的差异）**约为原子工具配置的 3 倍**。原因在于模型被迫在单次前向 pass 里规划整段变更，没有任何中间窗口去核对状态。 ```python # 巨型单工具：一次性接收完整变更计划 edit_document( operations=[ {"type": "delete", "at": 412, "len": 23}, {"type": "insert", "at": 412, "text": "..."}, {"type": "format", "range": [412, 480], "style": "h2"}, # 模型必须在脑子里算清前面每步对后面偏移量的累积影响 ] ) ``` 致命的是 index drift：模型在"假想的同一份计划"里假设第 412 字符位置的标题还存在，可前面一个假想删除已经把偏移量推走了，结果是引用到一个不存在的索引，文档被腐化到连下一轮 agent 都难以挽救。巨型工具省下的 token，在一个被毁掉的编辑面前一文不值。 ### 二、纯原子工具：准确红利与 25 工具悬崖 把 `find`、`delete_substring`、`insert_string`、`replace_range` 全部拆成独立工具，把验证逻辑挤进模型的推理回路——对前沿指令微调模型，这条路准确率最高。但 token 计数会膨胀，而且实测发现一条清晰的断崖：**当工具表面超过约 25 个时，模型开始在近义词之间误选**。`insert_paragraph`、`insert_text`、`append_text`、`prepend_text` 在语义上高度聚集，模型分不清该用哪个，这是 8 工具配置里根本不存在的失败模式。 更反直觉的是工具数量与**命名熵**的交互：20 个名字聚集的工具（全是 `insert_*` / `append_*`），比 30 个动词明显不同的工具更难选对。也就是说，拖垮模型的不是绝对数量，而是名字空间的语义拥挤度。这条结论直接打脸了"工具越多越糟"的朴素直觉——30 个动词鲜明的工具可以稳跑，20 个近义词堆在一起反而崩。 ```python # 近义工具聚集：模型在此处高频误选 tools = ["insert_paragraph", "insert_text", "append_text", "prepend_text", "add_block", "push_content"] # 命名熵过高 # 应合并为 2 个动词鲜明的工具： tools = ["insert_at(index, text)", "append_to(section, text)"] ``` ### 三、宏的命名陷阱：`composeFormatBatch` 被无视，`replace_all` 被秒用 混合配置是综合分最高的形态：原子原语覆盖长尾，再加 **3–5 个命名得当的宏**压缩最高频的多步序列。`replace_all`、`format_all_matches`、`convert_paragraph_to_heading` 这类宏能把 4 次往返压成 1 次。但宏的成败不在数量，而在于它是否对应一个用户真正会说的自然语言请求。 实测给出了一个残酷的对照：为代码优雅而发明的宏（如 `composeFormatBatch`）会被模型完全忽略，因为它宁愿走原子原语也不猜一个语义模糊的宏；而用自然语言命名的宏（如 "replace all X with Y"）会被立刻、正确地使用。这意味着工具设计者不能从代码架构出发去切宏，必须从**用户的请求语料**出发去切——宏的本质是"高频自然语言意图的缓存"，不是"代码复用的抽象"。训练营里这一节最值钱：它把工具设计从工程审美拽回了产品语言。 ### 四、结构性验证 vs 提示词验证：幻觉 14% → <2% 模型在状态敏感操作（文档、缓冲区、语法树）上最容易犯的错，是引用一个已经偏移的索引。AgentDoc 给出的最强实战结论是：**别靠提示词让模型"修改前先重读"**。提示词验证有时灵有时不灵；而一个 State-Constrained ReAct FSM——把所有写工具锁住，直到一次 `get_document_context` 调用完成才解锁——**百分之百有效**。 ```python # FSM 门控：写工具必须挂在"最近一次重读"之后 if time_since_last_get_context > STALE_THRESHOLD: force_tool("get_document_context") # 结构性强制重读 block_write_tools() # 写工具在重读完成前不可用 else: allow_write_tools() ``` FSM 配置把幻觉索引错误从纯提示词条件下的约 **14% 砍到 2% 以下**，成本只是每隔几轮多一次往返——相对于一次腐化的编辑，这点延迟几乎免费。教训很硬：如果一个失败模式的后果是"全局腐化而局部成功"，那它绝不能交给提示词自律，必须在工具表面的结构里让它不可发生。 ### 五、index drift 是工具设计 bug，不是模型 bug 很多人把索引漂移归咎于模型笨，实测否定了这个甩锅。最差表现的配置不是"模型能力弱"，而是**工具契约允许模型局部成功而全局失败**。一个接收字符索引、返回 success、却不告诉模型"该索引之后的内容已整体偏移"的工具，就是 bug 本身。 ```python # 正确的变更工具应返回 dirty-range 描述符 def delete_range(index, length): ... # 执行删除 return { "status": "ok", "shifted_after": index, # 此处之后的内容已移动 "delta": -length # 偏移量：负值表示整体前移 } # 下一轮工具调用看到这个，FSM 据此触发重读 ``` 修正方案是让每个变更工具返回结构化的 `dirty-range` 描述符（`{shifted_after: 412, delta: -23}`），下一轮工具调用能看到它，FSM 据此门控重读。加上这个反馈通道后，幻觉跌到接近地板。前沿模型迟早会自己学会补偿，但你的工具表面不该要求它们必须学会。这条原则对训练营产品的价值在于：它能被包装成"工具契约审查清单"，是个能直接卖给企业工具团队的可交付物。 ### 六、双重 token 税：定义过载 + 中间结果回流 Anthropic 官方工程文章点出了工具扩张时的两条 token 失血线。第一是**工具定义过载上下文窗口**——大多数 MCP 客户端把全部工具定义一次性塞进 context，连上千工具的 Agent 在读到用户请求前就要先消化几十万 token 的定义。第二是**中间工具结果回流**：一个"从 Google Drive 下载会议纪要并附到 Salesforce 线索"的请求，完整纪要文本会被塞进 context，模型再把它原样写进第二个工具调用，一份 2 小时会议纪要（约 5 万 token）就这样在 context 里过了一遍半，大文档甚至直接撑爆窗口。 ```python # 直调模式的 token 税：中间结果两次过 context r1 = gdrive.getDocument("abc123") # 5万 token 进 context salesforce.updateRecord(notes=r1.body) # 5万 token 再写一遍进 context ``` 破局不是改工具粒度，而是改**交互范式**：把 MCP server 呈现为 code API 而非直接 tool call，让 agent 写代码去调工具，在执行环境里就地处理数据，只把精简结果回传给模型。这绕开了"模型当搬运工"的低效，把粒度问题转化为编排问题。 ### 七、代码执行 + Tool Search：省 34–64% token 延续上一条的范式转换，2026 年出现了两条成熟的省 token 手法。其一是 **Tool Search Tool 模式**（Anthropic 内部工具首创，Spring AI 于 2025 年 12 月在 MCP 集成中正式化）：初始只给模型一个"搜索工具"的能力，模型按需查询相关工具定义，只有被命中的定义才展开进 context。生产基准显示，这一模式让**总 token 消耗下降 34–64%**，降幅随模型和搜索策略波动。 ```typescript // MCP 工具以代码文件树形式组织，按需 import // ./servers/google-drive/getDocument.ts import { callMCPTool } from "../../../client.js"; export async function getDocument(input: { documentId: string }) { return callMCPTool('google_drive__get_document', input); } // agent 写代码：数据在执行环境流转，不回灌模型 context const doc = await getDocument({ documentId: "abc123" }); await updateRecord({ notes: doc.content }); // doc.content 不进 context ``` 其二是**并行函数调用默认化**：OpenAI 自 2025 年 3 月 Agents SDK 起把并行 tool call 设为默认行为，单轮内可批量发起无依赖调用。配合 Structured Outputs（`strict: true` + 约束解码，保证 100% schema 符合），工具调用的可靠性补丁基本打齐。这两条都不动粒度，却实打实改变了巨型/原子各自的税负曲线——原子工具的 token 膨胀被 Search 压住，巨型工具的可靠性短板被 strict schema 部分兜底。 ### 八、BFCL V4 榜单的天花板：换模型不如改约束 Zylos Research 的 2026 年盘点把工具调用的成熟度量化到了 BFCL V4（首次评测 agentic 多步行为而非单调用准确率）。榜单头部集中在一个尴尬区间：**Claude Opus 4.1 以 70.36% 居第 2，Claude Sonnet 4 以 70.29% 居第 3，GPT-5 以 59.22% 排第 7**。也就是说，最强的 Agent 模型在多步工具调用上也只有约七成准确率——榜单封顶的形状，恰恰是前面六条深度分析的背景板。 ```mermaid flowchart TD A[用户自然语言请求] --> B{命中宏?} B -- 是 --> C[调用命名宏
replace_all / format_matches
4次往返压成1次] B -- 否 --> D[Tool Search 按需展开
仅相关定义进 context] D --> E[原子原语执行
find / insert / delete] C --> F[变更工具返回
dirty-range 描述符] E --> F F --> G{FSM 门控:
距上次重读是否过期?} G -- 过期 --> H[强制 get_context 重读
写工具上锁] H --> I[解锁写工具] G -- 未过期 --> I I --> J{还有未决变更?} J -- 是 --> D J -- 否 --> K[输出最终结果] style B fill:#fff3cd style G fill:#f8d7da style H fill:#d4edda ``` 榜单的潜台词是：**在 70% 的天花板下，靠换模型挤几个百分点，远不如靠结构性约束把失败模式根除来得划算**。FSM 门控、dirty-range 反馈、命名宏、Tool Search——这些工具表面层的工程动作，单位投入的准确率回报，普遍高于"升级到下一代模型"。这也是为什么粒度税值得单独成篇：它处在模型能力够不着、又恰好是工程杠杆最敏感的地带。 ## 推荐方案 **文档/代码编辑类状态敏感场景**：原子基座 + 3–5 个自然语言宏 + FSM 门控验证，是唯一稳态组合。巨型工具的 token 甜头在该场景会被 index drift 全额罚没，切勿贪。 **CRUD SaaS 集成（Salesforce/Drive/Slack）**：用 Tool Search Tool 模式，工具表面保持在 25 以下并按动词分组，规避命名熵悬崖；大量工具用代码执行 API 编排，中间结果不回灌 context。 **数据分析/报表类**：天然适合代码执行范式，把工具暴露为可被 agent 编程的函数库，让模型写 pandas 代码批量调，而非逐个 tool call——这是粒度问题向编排问题的标准转化。 **MCP 多 server 大规模场景**：放弃"全量定义进 context"，强制 Tool Search + 按需展开，目标把 token 税压在 34–64% 的实测降幅区间内。 **训练营/产品包装**：以"原子 + 命名宏"为主轴，把宏的命名陷阱（`composeFormatBatch` vs `replace_all`）做成最反直觉、最有传播力的一课；把 dirty-range 描述符和 FSM 门控整理成可交付的"工具契约审查清单"，是企业工具团队愿意直接买的形态。 **一句话总纲**：默认走原子原语，只把用户真正会说的高频请求做成宏；任何"局部成功、全局失败"的契约漏洞用结构堵死，不交给提示词自律；token 税用 Tool Search 和代码执行范式压，而不是靠减少工具数量硬扛。 ## 参考来源 1. [Tool Granularity in LLM Agents – 20 Workflow Configurations (AgentDoc)](https://agent-doc-edit.com/blog/tool-granularity-llm-agents) — 20 配置 × 13 基准实测，巨型工具 3× 准确率差、25 工具悬崖、FSM 门控 14%→<2% 等核心数据来源。 2. [Code execution with MCP: Building more efficient agents (Anthropic Engineering)](https://www.anthropic.com/engineering/code-execution-with-mcp) — 工具定义过载、中间结果双重 token 税、code API 范式破局的官方依据。 3. [Tool Use and Function Calling in AI Agents — Standards, Benchmarks (Zylos Research, 2026-04-07)](https://zylos.ai/research/2026-04-07-tool-use-function-calling-standards-benchmarks/) — BFCL V4 榜单（Opus 4.1 70.36%、Sonnet 4 70.29%、GPT-5 59.22%）、Tool Search 34–64% 降幅、Structured Outputs。 4. [Benchmarking Agent Tool Use (LangChain Blog)](https://www.langchain.com/blog/benchmarking-agent-tool-use) — 跨模型工具使用基准方法与测试环境对照。 5. [Tool (aka Function Calling) Best Practices (Laurent Kubaski, Medium)](https://medium.com/@laurentkubaski/tool-or-function-calling-best-practices-a5165a33d5f1) — MCP 语境下的工具命名、参数设计与粒度实践。 > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。