toolgz：把工具定义 token 砍掉约 80% 的开源压缩库

近日在 Hacker News 上亮相的开源库 toolgz 试图解决一个被多数智能体开发者忽视的隐性成本：在用户尚未输入任何内容前，工具定义就已经占用了大模型上下文窗口的相当一部分。开发者每接入一个 MCP 服务器，往往会带入 20–50 个工具；每个工具的 JSON Schema 加上参数说明，平均约 420 个 token，其中约 400 个 token 是模型在做工具选择时其实并不需要的描述性文字。累积起来，50 个工具约 2 万 token，100 个工具约 4 万 token。提示缓存（prompt caching）可以让这些 token 变得便宜，但无法让它们从上下文中消失——而 toolgz 瞄准的正是后者。

核心思路与接入方式

toolgz 提供了三行级别的接入 API：先用 compress 处理既有的 MCP/SDK 工具数组，再用 forAnthropic 这类适配器生成「压缩后的工具 + 系统提示」传给模型；模型返回的工具调用经 resolve 还原为真实的工具名与参数，下游派发逻辑无需修改。其核心机制是将一长串原始工具定义替换为极简的「代号 → 真实工具签名」映射，并提供按需展开（lookup）能力，把工具选择从「回忆」问题转化为「检索」问题。

跨厂商基准：四模型、七策略、420 次运行

工具作者公布了一轮跨厂商扫描的结果，覆盖 4 个前沿模型、7 种压缩策略、5 个工具选择任务、每个组合 3 次重复，共计 420 次运行，跨多轮累计 1200+ 次，且每次原始记录都提交在仓库的 bench/results/ 目录中，可一键复算。要点摘录如下：

• Anthropic claude-opus-5：工具块从 9,242 → 1,284 token；总提示 30,817 → 4,628 token（−85%）；成本 −78%；延迟 15.0s → 12.1s；任务 15/15。
• xAI grok-4.5：6,421 → 775 token；总提示 −85%；成本 −70%；延迟 6.1s → 4.6s；15/15。
• Google gemini-3.1-pro-preview：5,264 → 732 token；−79%；成本 −62%；5.6s → 5.5s；15/15。
• OpenAI gpt-5.6-sol：2,753 → 573 token；−71%；成本 −7%；6.8s → 5.6s；15/15。

全部模型均开启高强度推理，4 家厂商合计 60/60 任务全部完成，未出现幻觉工具名或畸形参数的情况，且延迟在每家厂商上都「不升反降」。

压缩级别与适用场景

工具内置 recommendLevel(myTools) 接口，可自动判断应使用级别 1 或 3（级别 2 被作者标注为「在每一项指标上都被级别 3 压制」）：

• 级别 1：每个工具作为原生 tool 暴露，使用签名行描述；默认推荐；零可测量的负面影响。
• 级别 3：一个分发器 + 一个查找工具；适合大型、深层工具集；上面 80% 的节省数字即来自此级别。
• 级别 0：透传模式，用于在自身应用里做 A/B 对照。

需要权衡的是：级别 2–3 下，模型填充的是一个通用参数对象，原生 schema 校验器不再强制类型；为此 toolgz 默认开启对原始 schema 的校验，并以模型可读的错误回传，作者建议保持开启。

边界与未解决的问题

作者坦承，OpenAI 上 −7% 的成本节省幅度明显小于其他三家，原因是其账单中推理输出占比更高、提示缩短对总成本的杠杆较小。文中因此把「上下文占用下降」作为主要主张，成本节省视作随推理设置变化的衍生收益。此外，第一轮扫描曾在 OpenAI 上出现成本反而上升 15% 的反例，作者将其归因于分发器多轮调用与三类 bug（参数 q 与 query 混淆、模型把映射代码当作工具名调用、参数展平而非嵌套），修复后 OpenAI 从 +15% 收窄至 −7%，并将所有厂商的畸形参数压到 0。整体而言，对于依赖大量 MCP 工具、又受限于上下文窗口的智能体开发者，这个工具提供了一个有数据支撑、可一键接入的优化选项。