如果你和我一样是个“手搓 Agent”的玩家，大概率经历过这样一条曲线：工具只有三五个时，怎么传都省心，模型基本指哪打哪；等工具涨到二十几个，问题就集体冒头了——每轮请求的 token 肉眼可见地涨，模型开始时不时选错工具，改一个字段要在项目里翻半天。这篇是《手搓 Agent 系列》的第二篇，聊的就是 Tool 规模化绕不开的三个工程问题：成本、选择、维护。这三个问题前期几乎是隐藏的，只有工具数量上来之后才会集中爆雷，而多数教程只教你“怎么加一个工具”，没人告诉你“加到很多之后怎么管”。
这篇文章基于我实际搭 Agent 的踩坑记录，把三个问题的成因、排查思路和一个轻量治理方案一次性说清楚。看完你至少能做到：工具再多也明白成本花在哪、模型为什么选错、改工具怎样才不连带翻车。内容不依赖任何重型框架，全部按“手搓”的思路来，适合正在自己搭 Agent、或者准备把 Agent 从 Demo 推向真实业务的开发者参考。
1. 工具一多就失控：规模化问题爆发的三个信号
先说怎么判断你已到需要治理工具的临界点了。我的标准很简单：工具数量接近或超过二十个，并且出现下面任意一个现象，就该停下来看看。
| 工具规模 | 每轮固定开销 | 模型选工具的感受 | 改一个工具的心理状态 |
|---|---|---|---|
| ≤ 5 个 | 几百 token | 基本不选错，指哪打哪 | 改了也不慌，反正代码里就一处 |
| 10 - 20 个 | 一到两千 token | 偶尔犯迷糊，选错后又能自己纠正 | 要全局搜一下哪里用到它 |
| 30 个以上 | 四五千 token 往上 | 明显开始瞎选，甚至跨工具乱塞参数 | 改完总觉得迟早要出事 |
这个表格不是拍脑袋写的，是同类项目里普遍能观察到的规律。原理上说，工具数量变多，本质上是把一块越来越大、互相重叠的描述文档塞进上下文，模型对单个工具的“注意力”被稀释，每轮固定开销也在同步抬升。成本、选择、维护三个问题不是独立出现的，它们都由同一个原因驱动：工具描述资产的膨胀。
1.1 别指望换框架能解决
聊到这，很多人第一反应是“那我换个更成熟的 Agent 框架，或者引入现成的工具管理组件，是不是就好了”。说实话，我试过。框架能帮你把工具注册和调度的架子搭起来，但它替代不了三件事：描述怎么写得省 token、选不准时怎么召回、工具变更后怎么保证不连带坏掉。框架只是把工具放进了一个容器，容器解决不了描述资产本身的质量问题。
而且框架还有一个反作用：它把工具变成了一种“配置项”，你反而更少去审视单个工具的描述和实现是否一致。等线上出了问题，排查链路又长了一层。这也是我坚持“手搓”一部分工具管理的原因——把机制握在自己手里，出问题时能直接从根上查，而不是先怀疑是不是框架的版本问题。
1.2 三个问题爆发的顺序
如果按时间线看，成本最先爆发，因为它是唯一一个能被数值感知的变量，账单不会骗人。选择其次，工具多了之后准确率下降是一个渐进过程，一开始不容易察觉。维护最后，但一旦爆雷往往最致命——改一个参数，静默影响所有调用它的任务。后面三节就分别对应这三件事展开。具体的临界数量跟任务复杂度有关，但经验上二十个左右确实是多数项目开始需要治理的起点。
2. 成本问题的本质是描述膨胀
很多文章一谈工具成本就喊“别塞太多工具”，但没说清楚钱到底花在哪。其实就一行账：当前主流模型 API 的 function calling 机制下，每次请求你都要把全部工具的 name、description、parameters schema 作为上下文的一部分发过去，这部分是固定开销，和你这次对话实际用了哪些内容无关。工具越多，固定开销越大，而且在多轮对话里它是被重复计算的。
2.1 算一笔具体的账
我按真实项目里很常见的规格来算：单个工具的描述加参数 schema 平均 200 token 左右。30 个工具，光 tools 参数就是 6000 token。一个需要 5 次模型调用的多轮任务聊下来，光工具描述就占掉 3 万 token。如果每百万 token 的输入成本按 4 元估算（各家差异很大，常见区间），那么每个任务光是工具描述就要多花 0.12 元。
单看一个任务不心疼，但日调用量上万的项目，一个月下来就是几万块的无谓消耗。工具描述确实是一种必要的信息载入，但其中至少有 60% 属于冗余。冗余主要来自三个地方：一是描述里反复出现同一套话术（比如“该函数用于……”每个工具写一遍）；二是参数 schema 里堆了大量可填可不填的字段，甚至把业务枚举值全泼进去；三是有些长期没人用的僵尸工具还留在列表里白白占位。
2.2 比 token 更贵的是延迟和上下文挤占
成本不只是账单上的数字。每轮请求多送几千 token，模型生成首字的时间会明显变长。哪怕多用一秒，对用户来说都是可感知的体验下降。另一个隐蔽问题更麻烦：工具描述会把上下文窗口里的“有效空间”挤占掉。比如你设定 8 万 token 的上下文，工具描述占了几千甚至更多，那么留给对话历史、检索结果、中间推理的空间就少了。任务一长，更容易撞上截断，或者模型为了省空间反而丢掉了该有的细节。
还有一类现象，是我在工具数量爬到 40 个左右才观察到的：模型开始把 A 工具的参数填进 B 工具。比如明明该调“汇率换算”，它却拿着金额字段去填“库存更新”的入参。这其实是注意力被过度稀释的表现，工具描述太长太杂，模型对参数边界的感知就模糊了。这类错误很隐蔽，单看日志很难发现，往往要等统计任务成功率时才暴露。
2.3 降本的姿势：分层投放，而不是少写点字
很多人听到这第一反应是“那我每个工具描述少写几十个字不就行了”。有用，但这是线性递减策略，治标不治本。真正有效的思路是分层投放。
至少把工具分成两层：高频核心工具和低频边缘工具。核心工具总是全量注入，边缘工具用一个极短的锚点描述（一行话 + 对应文档编号）占位，只有在检索确认这个任务确实需要它时，才把完整描述送进去。一句话原则：高频全量，低频兜底，命中再补全。
这里多说一句：动态拼装工具描述，比把描述静态写死在系统提示词里更抗风险，因为你能在运行时根据用户 query 决定“要不要带上这个工具”。这也是下一节选择问题的基础。我后来把“什么时候该给模型看哪些工具”这件事专门抽了一小块逻辑出来，没有混在业务代码里，后面会给一个可参考的骨架。
3. 选择问题的本质：从“全量猜”到“召回 + 精排”
工具选择是三个问题里最容易被误解的一个。很多人以为把工具描述写得清楚、字段补全，模型就能一直选对。早期确实如此，工具少、描述之间差异大，靠语义匹配就能精准选中。但工具一旦多起来，多个工具的描述在语义上开始重叠——比如“库存查询”“订单查询”“物流查询”，都是查询，用户一句“查一下这个订单到哪了”，模型得在好几个相关工具之间猜。
3.1 模型实际上在做什么
从行为上去推：大模型在训练时会根据“用户意图 → 可用工具列表”的配对数据学习一种相关性打分，运行时它会隐式地对每个工具描述和当前 query 算相关性，然后挑得分最高的那个调用。注意，它面对的是一个静态长列表，得分受描述长度、位置、和其他描述的区分度影响很大。工具一多，相当于你让它在几百行文档里做阅读理解再选答案，这本来就超出了模型最适合的任务区间。
3.2 三种主流方案对比
我把接触过的工具选择方案整理成了一张表，方便直接对照：
| 方案 | 原理 | 每轮额外成本 | 选对率表现 | 适合阶段 |
|---|---|---|---|---|
| 全量塞入 | 所有工具描述都传给模型 | 无额外成本，但固定 token 高 | 工具少时很高，多时骤降 | 工具 ≤ 10 个 |
| 规则路由 | 关键词 / 业务分类写死，命中则传入对应工具组 | 极低，纯规则 | 稳定但僵硬，边界情况容易漏 | 工具边界清晰、业务变动少 |
| 召回 + 精排 | 先把工具描述做向量化预选 top-K，再交给模型最终决定 | 一次 embedding 调用，很便宜 | 高，且随数据积累可提升 | 工具 20 个以上，描述质量可控 |
我现在的方案就是“召回 + 精排”。召回层用向量相似度把 30 个工具的候选列表砍到 5-6 个，精排层还是让模型自己挑，但它的挑选范围已经小了很多。代价是每次多一次 embedding 调用，这个调用比大模型生成便宜一到两个数量级，换来的是工具选择准确率明显提升。
这里有一个重要的策略：召回交给向量，最终决策一定还是交给模型，不要用向量分数直接硬选。因为 embedding 对业务语义的理解远不如模型，硬选很容易把表述相近但意图不同的工具选错。召回只是缩小范围，不是做最终裁决。
3.3 落地会翻车的几个细节
第一，向量化的对象是“工具描述 + 路由关键词 + 典型 query 示例”，不是工具名。工具名往往只有一两个词，向量化后信息量太低。我早期只向量化名字，召回效果差到差点放弃这个方案。第二，不同团队对同一个业务叫法不一样，比如“订单查询”有的叫“查单”，有的叫“订单状态”，所以描述里要加 route_keywords 字段，把这类表达归一进去再向量化。第三，阈值要留余量。我的经验是阈值宁可调低，让 6-8 个候选进去，也不要调高到只进 2-3 个——漏掉正确工具比让模型多选一次严重得多。一旦正确工具被召回层滤掉，精排层再有本事也白搭。
4. 维护问题：改一个参数，三个地方等着你
如果说成本和选择是“使用期”的问题，维护就是“变更期”的问题。工具不可能永远不变：业务参数要加字段，接口要换协议，排序逻辑要调整。我踩过的坑基本可以归成三类死法。
4.1 三种典型故障
第一种是参数变更失同步。有一次我给某个工具调换了入参字段名，实现改了、调用处改了，唯独忘了 tools 描述里的 JSON Schema 还是旧字段。结果线上 Agent 不再报错，而是直接按旧 schema 生成参数，服务端收到后静默忽略，任务长期假成功。这类问题最阴的地方在于，它不崩溃，只是悄悄产出坏结果。
第二种是语义漂移。工具行为变了，描述没跟着变。比如某次我把“库存查询”改成了优先返回可售库存，但描述里写的还是“返回全部库存”，模型按旧理解去判断库存是否充足，导致不少订单流程被错误拦截。工具的行为和它的描述之间，本质上是一条约定，约定一旦和实现脱节，模型就成了被错误信息蒙在鼓里的执行者。
第三种是僵尸工具。代码里注册了一堆长期没人调用的工具，每次请求都还带着，浪费钱也干扰选择。僵尸工具不是一次产生的，往往是被局部需求遗留下来，或者当时觉得“以后会用”就再没启用。做治理时，我发现最有用的判断标准不是注释里有没有人认领，而是最近 30 天里有没有任何一条链路实际调过它。
4.2 让维护可观测：描述、实现、测试三合一
应对以上问题，我的做法是把每个工具当成一个“注册项”来管理，而不是散落在代码里的一堆函数。一个注册项里必须有：实现函数、描述文本、参数 schema、版本号、启用状态。三样东西放同一个文件里，改的时候天然要一起改。
在此基础上再加两个自动检查。一是 schema 校验，用实现函数的签名和入参定义去比对描述里的 JSON Schema，名字对不上直接报错。二是描述长度检测，超过预设 token 阈值的描述标红，倒逼精简或分层。
其实维护问题最有效的解药是可观测性，而不是更自律。靠人记忆去同步工具描述和实现，早晚出纰漏。但如果你每次构建前跑一遍“工具体检”，把不一致、超标、僵尸三类问题全部列出来，绝大多数事故都能在发版前被拦下来。
4.3 版本号不是摆设
最后说一个经常被忽略的点：工具版本。一个正在跑的长对话 session 可能用了三天前的工具描述，你今早改了工具行为，但会话里模型还是按旧描述生成参数，新旧一混，问题就出来了。我给每个工具都加了 version 字段，会话里记录本次用到的工具版本集合。排查问题时先看版本是否匹配，而不是先怀疑模型飘了。这个习惯帮我快速定位了好几次“莫名其妙”的线上异常，排查时间从小时级压缩到分钟级。
5. 一套轻量工具治理方案的实际落地
前面讲了这么多原理，这里给一套我个人在用的轻量骨架。它不依赖任何重型框架，核心就是一个注册表、两条链路、一个体检脚本。代码写得尽量贴近可直接跑的状态，但重点还是看思路。
5.1 核心数据结构与注册
先定义一个最小的工具规格：
@dataclass class ToolSpec: name: str # 工具名，模型在 function call 里会用到 desc_full: str # 详细描述，用于最终交给模型的版本 desc_short: str # 锚点描述，用于召回与分层投放 schema: dict # 参数 JSON Schema，和实现签名校准 keywords: list # 路由关键词/别名，用于向量化召回 version: str # 版本号，如 "2025.02.1" active: bool # 是否启用，停用不等于删除 impl: Callable | None = None # 实际实现的函数注册表就是一个字典：
TOOL_REGISTRY: dict[str, ToolSpec] = {} def register(spec: ToolSpec): TOOL_REGISTRY[spec.name] = spec每个工具写成一个注册函数，实现和描述放在一起，避免散落。这里最关键的是“impl 和 schema 必须同源”——schema 要么由函数的类型注解推导，要么在注册时用一个校验器去比对，否则维护问题一定复发。我用的是第二种思路，注册时跑校验，报错就不让注册，从入口挡住失同步。
5.2 两条链路：离线注册与在线召回
离线链路在启动或构建阶段做一次：遍历注册表，把所有 active 工具的（desc_short + keywords + 典型 query）拼成文本，批量生成 embedding，直接存成 numpy 矩阵。工具数量通常远小于需要引入向量数据库的量级，所以没必要上重组件。
在线链路的处理流程是：拿到用户 query → 生成 query 的 embedding → 和所有工具向量做相似度 → 取 top-K 候选 → 对候选做全量描述拼装 → 交给模型。核心代码其实就十几行：
import numpy as np def retrieve_tools(query_vec: np.ndarray, k: int = 6): scores = TOOL_MATRIX @ query_vec # 所有工具向量与 query 点积 top_idx = np.argsort(scores)[-k:][::-1] return [TOOL_NAMES[i] for i in top_idx if scores[i] > THRESHOLD]候选工具拿到之后，把它们的 desc_full 和 schema 装进当前请求的 tools 参数；没被召回的边缘工具，只放一个 desc_short 行占位，甚至完全不放，等后续动态补全。这个流程每一步都不复杂，但组合起来能解决成本、选择两个问题的大头。
5.3 体检脚本：把维护问题提前拦下
体检脚本是我每轮发版前必跑的东西，逻辑很简单，就是三个检查：
# 伪代码，实际按项目语言实现 check tool_schema_vs_impl # 实现签名与 schema 字段一致性 check tool_desc_token # 每个 desc_full 是否超预算（默认 300 token） check tool_zombie # 统计近 N 天调用日志，标出零调用工具第一个和第二个是静态检查，秒出结果。第三个要依赖调用日志。我把每次 function call 的名字打一条结构化日志，累积下来就能统计。僵尸检查一个月跑一次就够了，发现连续 30 天零调用的工具，先置为 inactive，而不是直接删掉。万一有链路还依赖它，快速回滚启用就好，不会返工。
5.4 实测效果与适用边界
我在一个 30 个工具的模拟 Agent 配置里跑过这套方案，效果按数据说话：每轮 tools 参数的 token 量从约 6000 降到约 1200，主要靠分层投放和召回后只带完整候选；端到端任务成功率从 82% 提升到 94% 左右；改一个工具参数从“全局搜代码 + 心里没底”变成“改一处 + 跑体检脚本 + 5 分钟确认”。这些是我自己项目的内部统计，不同任务差异很大，但趋势是明确的。
当然也不是所有项目都该上这套东西。我判断的工具数量临界点是：10 个以下，全量注入 + 简洁描述就够了，上向量召回属于过度设计；10-30 个，优先做 desc_short 和静态分组，可能不需要向量召回；30 个以上或描述经常语义重叠，再引入动态召回。治理成本本身也是一种成本，别为了治理而治理。
6. 可复用的经验与度量标准
最后分享一些可以直接抄走的小经验，这部分不展开讲原理，都是我反复验证过有效、能立刻用的东西。
6.1 工具描述的四句话黄金结构
写工具描述，不需要小作文。我用一个四句话结构，覆盖率和省 token 都照顾到：
- 这个工具做什么（一句话，动词开头）。
- 什么场景下优先用它（给模型触发条件）。
- 什么场景下不要用它（明确边界，防误用）。
- 调它的时候参数怎么约定（只写关键字段约定，不复制整个 schema）。
举个例子。反例是：“本函数用于查询系统中的订单数据，返回订单列表、订单金额、订单状态等信息，其中参数 order_id 必填，status 选填，可传入 1 表示待支付、2 表示已支付、3 表示已发货……”这种写法又长又没边界。
正例是：“查订单列表。当用户问‘我的订单到哪了’或‘买过什么’时使用。只用于查询，不用于下单和退款。传入 order_id 或 customer_id，其余字段按默认；状态码用数字表示，具体码表见 schema。”后者 token 更少，信息密度反而更高，因为边界和触发条件都写清楚了。模型拿到这种描述，既知道什么时候调，也知道什么时候不该调，误用率会明显下降。
6.2 三个度量指标
我平时衡量工具系统健不健康，只看三个数：
| 指标 | 怎么算 | 我的经验值 |
|---|---|---|
| 工具定价成本 | 一份工具描述的 token 数 × 预计调用次数 | 单工具描述 ≤ 1% 的上下文预算 |
| 工具召回率 | 被召回的候选里正确工具出现的比例 | 目标 ≥ 95%，漏召回是最大事故 |
| 变更事故数 | 每季度因工具变更导致线上异常的次数 | 目标趋零，靠体检脚本和版本号兜底 |
这三个指标不是一次性算完就结束，要放进每个版本迭代的评审里。工具治理最大的陷阱就是“感觉没问题”，三个可量化的指标能逼着你去看真实数据，而不是凭印象。
6.3 关于“手搓”的一点体会
写到这里想多说一句。这套东西不复杂，按理说框架和平台应该能替你管，但亲手搓一遍之后，你对 token、描述、schema 三者耦合关系的理解是完全不一样的。后来我用任何现成的框架，都会特意去确认它有没有覆盖“描述与实现一致性检查”“工具版本追溯”“边缘工具动态注入”这几件事。没有这些，不管什么框架，工具一多依然会踩同样的三个坑。
最后分享一个小习惯：每次发版前跑一遍工具体检，然后把超 token 和零调用的工具列表贴到项目群里，让对应负责人认领。这个动作极其简单，但它逼着每个工具三周内要么被优化、要么被停用、要么被删掉，比任何制度都有效。如果你也正在被工具规模化折磨，建议从这一条开始试起。
