1. 六十个工具摆在面前Agent 为什么反而不会干活了给 Agent 挂工具这件事很多人一开始的想法特别朴素工具越多能力越强能干的活越多。于是从文件读写、网页抓取、数据库查询到发邮件、调接口、跑脚本一口气塞进去五六十个。结果跑起来一看Agent 不是变强了而是变傻了——该调 A 工具的时候它去调 B该传三个参数它只传一个甚至面对一个简单任务反复横跳最后给你返回一句我无法完成该请求。这个现象我把它叫做工具过载。它不是模型能力不够而是决策空间被撑爆了。你想想自己打开一个塞了六十个按钮的遥控器每个按钮功能都沾点边你第一反应也是懵的。Agent 面对的是同样的处境它要在每一步从六十个候选里挑一个而每个工具的名称、描述、参数 schema都会作为上下文喂给模型。工具一多光是这些元信息就能吃掉几千甚至上万 token真正留给任务推理的空间被严重挤压。关键词里出现的Agent、MCP、Spring AI、LangChain4j这几个词其实指向的是同一件事的不同层面。Agent 是执行主体MCP 是工具接入的协议标准Spring AI 和 LangChain4j 是 Java 生态里把这两者串起来的框架。工具给到六十个之后挑花眼本质上是工具注册、工具描述、工具选择这三个环节里至少有一个出了问题。这篇内容我就围绕这个场景把工具过载的成因、排查路径、以及可落地的收敛方案讲透适合正在用 Java 做 Agent 开发、或者刚接触 MCP 协议想搞清楚工具治理的同行参考。先说结论避免你看到一半才发现方向不对工具数量本身不是问题工具之间的语义重叠和描述质量才是问题。六十个工具如果彼此边界清晰、描述精准Agent 照样能选对但如果其中二十个工具的描述都写着用于处理数据那模型不懵才怪。下面我按为什么会懵—怎么定位—怎么收敛—怎么验证的顺序展开。2. 工具过载的真实成因不是数量是决策熵2.1 工具描述同质化让模型无法区分我见过一个典型的工具集里面同时存在这几个工具queryData、fetchData、getData、retrieveData。四个工具的描述分别是查询数据获取数据得到数据检索数据。你让一个资深工程师来选他都要愣三秒更别说模型了。模型做工具选择靠的是语义匹配——把当前任务意图和工具描述做相似度计算。当四个描述几乎同义时相似度分数会非常接近模型只能随机挑一个挑错的概率高达 75%。这种同质化在 Java 项目里特别常见因为很多团队是多人协作A 同学写了一个UserService.queryUserB 同学不知道又写了一个UserService.getUserInfo两个方法都被注册成工具功能重叠度 90%。MCP 协议本身不负责去重它只负责把工具暴露出去去重和治理是开发者自己的事。2.2 参数 schema 膨胀挤占推理上下文每个工具注册时都要带上参数定义。一个稍微复杂点的工具参数 schema 可能有五六个字段每个字段还有类型、描述、是否必填。六十个工具平均每个 150 token 的元信息加起来就是 9000 token。这 9000 token 是每一轮对话都要重新喂给模型的因为模型需要知道当前有哪些工具可用。上下文窗口是有限的。假设你用的是 32K 窗口的模型9000 token 给了工具定义再扣掉系统提示词、历史对话、当前任务描述真正留给模型思考该怎么做的空间可能只剩一半。模型在推理时被迫在更短的思维链里做决策出错率自然上升。这就是为什么很多团队发现工具从 20 个加到 60 个任务成功率不升反降。2.3 工具选择缺乏分层导致扁平决策人类专家处理复杂任务时会分层先判断这是数据类任务还是通信类任务再在类别内选具体工具。但大多数 Agent 的工具注册是扁平的六十个工具平铺在一个列表里模型要在一次决策里从六十个中选一个。这相当于让你在一个没有分类的通讯录里找一个人效率极低。LangChain4j 和 Spring AI 目前主流的工具注册方式都是扁平的Tool注解或者ToolCallback列表框架层面没有强制你做分层。分层需要开发者自己在提示词或者路由逻辑里实现。这一点后面会讲具体做法。2.4 工具副作用未标注引发连锁误操作还有一个隐蔽的坑工具分只读和有副作用两类。查询数据库是只读的发邮件、删文件、下单是有副作用的。如果六十个工具里混着这两类而描述里没有明确标注模型可能在探索阶段误调有副作用的工具造成不可逆的后果。我遇到过最离谱的一次Agent 为了确认文件是否存在调用了deleteFile工具然后检查返回值——因为那个工具的描述写的是操作文件。这种事故的根因就是工具的危险等级没有暴露给模型。MCP 协议里有annotations字段可以标注readOnlyHint、destructiveHint但很多实现根本没填。3. 定位问题怎么判断你的 Agent 是工具过载而不是模型不行3.1 看工具调用日志的三个关键指标不要凭感觉判断去看日志。我通常盯三个指标指标含义健康值过载信号工具选择准确率选对工具的次数 / 总调用次数 90% 70%平均决策轮次完成任务平均需要几轮工具调用2-4 轮 8 轮无效调用率调用后结果未被使用的比例 10% 30%如果这三个指标里有两个亮红灯基本可以确认是工具过载。注意决策轮次多不一定是坏事复杂任务本来就需要多轮但如果一个查天气的简单任务跑了 8 轮那就是工具在互相干扰。3.2 用消融实验确认是哪些工具在捣乱定位到过载之后下一步是找出害群之马。我的做法是消融实验把六十个工具分成若干组每次禁用一组跑同一批测试任务看成功率变化。具体操作上如果你用的是 Spring AI可以在注册ToolCallback的时候加一个开关配置通过配置文件控制哪些工具生效。跑三轮下来通常能锁定 5-10 个高干扰工具——它们要么描述模糊要么和其他工具功能重叠。把这些工具下线或者重写描述成功率往往能回升 20 个百分点以上。3.3 检查工具描述是否触发了模型的犹豫有个很实用的技巧把工具列表和任务一起喂给模型让它只输出它想调用的工具名不执行。然后看它输出的分布。如果同一个任务跑十次模型选了五个不同的工具说明这几个工具的语义边界模糊。如果十次都选同一个但选错了说明是描述误导。这个只选不执行的探测方式在 LangChain4j 里可以通过自定义ToolSelector实现或者干脆用一个独立的提示词模板手动跑。成本很低但能快速暴露描述问题。4. 收敛方案把六十个工具治理成看起来只有十个4.1 工具合并把同义工具收敛成一个带参数的入口第一步永远是去重。queryData、fetchData、getData、retrieveData这四个合并成一个queryData通过一个source参数区分数据来源。合并后工具数量直接砍掉四分之三而且模型的选择变明确了。合并的原则是如果两个工具的差异可以用一个枚举参数表达就合并。比如queryMySQL和queryPostgres合并成queryDatabase(dialect: mysql | postgres)。但如果两个工具的业务语义完全不同比如发送邮件和查询订单就不能硬合并那会让描述变得又长又模糊。在 Java 里做合并通常是在 Service 层之上包一层ToolFacade把多个底层方法聚合成一个对外工具。Spring AI 的Tool注解支持在方法上定义你完全可以在 Facade 方法里根据参数路由到不同的底层实现。4.2 工具分层用路由 Agent 做两级选择扁平列表改成两级。第一级是领域路由把工具按业务域分成数据域通信域文件域计算域等每个域 5-8 个工具。第二级才是具体工具选择。实现方式有两种。一种是提示词分层系统提示词里先让模型判断任务属于哪个域再加载该域的工具列表。另一种是代码路由用一个轻量分类器甚至可以是关键词匹配先判断域然后只把该域的工具注册给模型。后者更可控我一般推荐后者因为分类器可以用规则实现不消耗模型推理能力。LangChain4j 里可以通过动态构建ChatLanguageModel的请求来实现——每次请求只带上当前域的工具。Spring AI 则可以通过ToolCallbackProvider的动态实现根据上下文返回不同的工具子集。4.3 描述重写让每个工具的描述具备排他性工具描述要满足三个条件说清楚做什么、说清楚不做什么、说清楚什么时候用。举个例子差的描述查询用户信息好的描述根据用户ID查询单个用户的详细信息包括姓名、邮箱、注册时间。 仅用于精确ID查询不支持模糊搜索模糊搜索请用 searchUsers。 当用户提供了明确的用户ID时使用此工具。好的描述里包含了排他性信息——明确告诉模型模糊搜索用另一个工具。这样模型在遇到模糊搜索需求时就不会误选这个工具。六十个工具如果每个都这样写模型的选择准确率会显著提升因为相似度计算有了明确的区分边界。4.4 危险工具隔离只读和有副作用分开注册把有副作用的工具单独放到一个高危工具集里默认不注册给主 Agent。需要时通过二次确认机制调用——Agent 先输出我打算调用 deleteFile请确认得到确认后才真正执行。MCP 协议里可以用annotations.destructiveHint true标注但更稳妥的做法是在框架层做拦截。Spring AI 可以自定义ToolCallback的包装器在调用前检查工具的危险等级危险工具走人工确认流程。LangChain4j 则可以通过ToolExecutor的装饰器模式实现。4.5 动态工具加载按任务阶段只暴露必要工具一个任务通常分几个阶段理解需求、收集信息、执行操作、验证结果。每个阶段需要的工具不同。按阶段动态加载工具能让模型在每一步面对的候选数从六十降到十以内。实现上可以在 Agent 的循环里维护一个当前阶段状态每进入新阶段就重新构建工具列表。这个思路在 MCP 里对应的是动态工具发现——MCP Server 可以根据客户端请求的上下文返回不同的工具集。不过大多数 MCP Server 实现是静态的动态加载需要自己在客户端侧做。5. 实操在 Spring AI 和 LangChain4j 里落地工具治理5.1 Spring AI 里的工具分组注册Spring AI 的工具注册核心是ToolCallback。默认情况下你把所有Tool方法所在的 Bean 交给ChatClient它就全注册了。要分组可以这样做// 定义分组标记 public interface DataTools {} public interface CommTools {} // 数据域工具 Component public class DataToolProvider implements DataTools { Tool(description 根据用户ID精确查询用户信息不支持模糊搜索) public User queryUserById(String userId) { ... } Tool(description 按关键词模糊搜索用户返回匹配列表) public ListUser searchUsers(String keyword) { ... } } // 通信域工具 Component public class CommToolProvider implements CommTools { Tool(description 向指定邮箱发送纯文本邮件) public void sendEmail(String to, String subject, String body) { ... } }然后在构建 ChatClient 时根据当前任务域选择性地注入ChatClient client ChatClient.builder(chatModel) .defaultTools(dataToolsOnly ? dataToolProvider : commToolProvider) .build();这样每次请求只带一个域的工具模型面对的候选数从六十降到个位数。注意Tool的description一定要写排他性信息这是提升准确率最廉价的手段。5.2 LangChain4j 的动态工具选择LangChain4j 的工具注册是通过AiServices的tools()方法。动态选择需要自己包一层public class DynamicToolSelector { private final MapString, Object toolGroups; public ListObject selectTools(String taskDescription) { String domain classifyDomain(taskDescription); return List.of(toolGroups.get(domain)); } private String classifyDomain(String task) { // 简单的关键词路由也可以用轻量模型 if (task.contains(邮件) || task.contains(通知)) return comm; if (task.contains(查询) || task.contains(数据)) return data; return general; } }然后在构建 AiServices 时传入动态选择的工具列表。LangChain4j 的AiServices.builder()支持在每次调用时重新指定工具这给了动态加载的空间。5.3 MCP 工具接入时的过滤策略如果你是通过 MCP 协议接入外部工具工具列表来自 MCP Server。这时候治理要在客户端侧做。MCP 客户端拿到工具列表后不要直接全量注册给模型而是先做一轮过滤ListMcpTool allTools mcpClient.listTools(); ListMcpTool filtered allTools.stream() .filter(tool - !tool.name().startsWith(internal_)) // 过滤内部工具 .filter(tool - tool.description().length() 20) // 过滤描述过短的 .collect(Collectors.toList());过滤规则可以根据实际情况调整。核心思路是MCP Server 提供全量工具客户端决定暴露哪些给模型。这个职责分离很重要因为 MCP Server 可能是第三方提供的你没法改它的工具定义但你能控制自己暴露多少。5.4 工具调用结果的压缩回传工具调用完结果要回传给模型。如果结果很长比如查询返回了 100 条记录全量回传会再次挤占上下文。我的做法是结果压缩只回传模型决策需要的关键字段或者做摘要。比如查询用户返回了完整对象回传时只给{id, name, status}三个字段。这个压缩逻辑可以写在工具包装器里对模型透明。LangChain4j 的ToolExecutor和 Spring AI 的ToolCallback都支持在返回前做处理。6. 验证与调优治理之后怎么确认真的变好了6.1 建立工具选择的回归测试集治理不能凭感觉要有测试集。我通常准备 30-50 个典型任务每个任务标注应该调用哪个工具。每次调整工具集后跑一遍看准确率。这个测试集不需要很复杂用 JSON 存任务和期望工具名就行。跑测试的时候要注意多次运行取平均因为模型有随机性。同一个任务跑 5 次看选对的比例。如果某个任务 5 次里选对 3 次说明这个工具的边界还是模糊需要继续优化描述。6.2 监控线上工具调用的分布上线后要持续监控。重点看两个分布工具调用频次分布和工具调用失败率分布。如果某个工具从来没被调用过要么它没用要么描述太差模型找不到它。如果某个工具失败率特别高可能是参数 schema 设计有问题。这些监控数据可以反哺工具治理——把高频误用的工具挑出来重点优化把从不使用的工具下线。工具集应该是一个动态收敛的过程不是一次配置就完事。6.3 用 A/B 测试确认治理收益如果条件允许做 A/B 测试一半流量走治理前的工具集一半走治理后的对比任务成功率和平均轮次。我做过的一次对比工具从 58 个收敛到 12 个分层后每层 12 个任务成功率从 61% 提升到 89%平均决策轮次从 7.2 降到 3.1。这个收益是实打实的。7. 几个容易踩的坑和我的经验第一个坑是过度合并。有人为了减少工具数量把功能差异很大的工具硬塞进一个结果参数变得极其复杂模型反而不会传参了。合并的前提是语义相近差异能用枚举表达。如果两个工具的业务逻辑完全不同宁可保留两个把描述写清楚。第二个坑是忽略工具返回值的格式。工具返回 JSON 还是纯文本对模型理解结果影响很大。我建议统一返回结构化 JSON字段名用英文值用简洁格式。纯文本返回值容易让模型误读尤其是包含换行和特殊字符的时候。第三个坑是忘记给工具加超时。六十个工具里只要有一个卡住整个 Agent 就挂起。每个工具调用都要有超时控制Spring AI 和 LangChain4j 都支持配置超时别用默认值。第四个坑是工具描述里写实现细节。描述是给模型看的不是给开发者看的。写调用 REST API 查询对模型没意义写查询用户信息才有意义。描述要站在任务意图的角度写不是站在技术实现的角度写。最后一个经验工具治理是持续过程不是一次性任务。业务在变工具在增今天治理好的工具集三个月后可能又膨胀了。建议把工具数量纳入监控指标超过阈值就触发一次治理。我自己的阈值是单层不超过 15 个工具超过就分层或者合并。这套方法我在几个 Java Agent 项目里都用过效果稳定。核心就一句话Agent 挑花眼不是因为它笨是因为你给的选择太多且太像。把选择收敛好把描述写清楚六十个工具也能让 Agent 用得明明白白。