1. 从“工具给到六十个”说起Agent 为什么会挑花眼“Agent 工具给到六十个它开始挑花眼”——这句话我第一次看到的时候脑子里立刻浮现出一个很具体的画面一个刚入职的实习生桌上被同时摊开了六十份不同的操作手册每一份都告诉他“用我准没错”结果他站在原地一份都不敢翻。Agent 也是一样的道理。这两年做 Agent 开发的人越来越多从 LangChain4j 到 Spring AI从 MCP 协议到各种 Agent 框架工具调用Tool Calling / Function Calling几乎成了标配能力。很多人上手的第一反应就是既然工具越多越强那我就把能接的都接上。搜索接一个、数据库接一个、文件读写接一个、浏览器自动化接一个、代码执行再接一个……接完一数六十个。然后跑起来发现Agent 不但没变聪明反而开始“犯迷糊”该调 A 工具的时候调了 B该传三个参数的时候只传了一个甚至干脆不调工具自己编一个答案糊弄过去。这不是模型变笨了而是工具选择本身就是一个决策问题而决策空间一旦膨胀到六十个选项任何模型都会出现选择困难。这篇文章我想把这件事掰开揉碎讲清楚工具数量到底在哪个区间是健康的、超过之后会发生什么、怎么用 MCP 和主流 Java 生态Spring AI、LangChain4j把工具组织得让 Agent 不迷路。适合正在做 Agent 项目、被工具调用折磨过的开发者也适合刚接触 MCP 协议、想知道“工具到底该怎么给”的新手。我先把结论摆在这儿工具不是越多越好六十个工具对绝大多数 Agent 来说已经严重超载。真正专业的做法不是“全给”而是“分层给、按需给、动态给”。下面从设计思路开始拆。2. 工具过载的本质Agent 到底在“挑”什么2.1 工具调用的决策链路拆解要理解 Agent 为什么挑花眼得先知道它在一次工具调用里到底做了哪些判断。很多人以为模型是“看到问题→选工具→执行”其实中间至少有三层决策第一层是意图识别用户这句话到底要不要调工具有些问题模型自己就能答有些必须查外部数据。这一层判断错了后面全错。第二层是工具选择如果要调六十个工具里选哪个模型看到的是每个工具的 name、description、参数 schema。它要在这些文本描述里做语义匹配。第三层是参数填充选定工具后从用户输入里抽取参数或者从上下文里推断参数。参数类型、必填项、格式约束都在这一层生效。六十个工具带来的最大压力在第二层。模型的上下文窗口是有限的六十个工具的完整 schema 塞进去光工具定义就可能吃掉几千甚至上万 token。更麻烦的是很多工具的 description 写得很像——“搜索网页”“查询信息”“获取资料”语义高度重叠模型根本分不清边界。提示工具描述的重叠度比工具数量更致命。十个语义清晰的工具往往比三十个描述模糊的工具更好用。2.2 上下文窗口与注意力稀释这里有个很多人忽略的机制注意力稀释。Transformer 架构在处理长上下文时并不是每个 token 都获得同等关注。当工具定义占据大量上下文后模型对每个工具描述的“注意力权重”会被摊薄。工具越多单个工具被准确识别的概率越低。我做过一个粗略的实测对比用同一批任务、同一个模型只改变工具数量工具数量工具选择准确率平均响应延迟参数填充错误率5 个约 96%低约 3%15 个约 91%中约 7%30 个约 78%高约 15%60 个约 55%很高约 28%这张表不是精确的学术数据是我在几个实际项目里观察到的趋势。可以看到从 30 个到 60 个准确率断崖式下跌。这就是“挑花眼”的量化表现。参数填充错误率飙升也很好理解工具一多模型容易把 A 工具的参数格式套到 B 工具上。2.3 六十个工具的真实来源为什么会有项目真的给到六十个工具我复盘过几个案例来源基本是这几类历史堆积项目迭代过程中不断加工具没人做减法旧的没删新的又加。能力贪多觉得“万一用得上”把搜索、爬虫、数据库、文件、邮件、日历、地图全接上。MCP 批量接入MCP 协议让接入外部工具变得极其简单一个 MCP Server 可能就暴露十几个工具接三四个 Server 就六十个了。团队协作不同模块的开发者各自加自己的工具缺乏统一治理。MCPModel Context Protocol的普及是双刃剑。它把工具接入标准化了mcp server一挂工具自动注册开发体验极好。但正因为太方便很多人失去了“克制”的意识。playwright mcp、chrome devtools mcp、burpsuite mcp、blender mcp这些现成的 Server 一接工具数量瞬间爆炸。3. 工具治理的核心思路分层、按需、动态3.1 分层设计把六十个工具收进几个“抽屉”解决挑花眼的第一招是分层。不要把所有工具平铺给模型而是先给模型几个“大类工具”让它先选类别再在类别内选具体工具。这就像把六十份手册先按部门分到六个抽屉实习生先找抽屉再找手册。具体做法有两种方案一工具分组 路由 Agent。用一个轻量的路由层可以是一个小模型也可以是规则先判断任务属于哪个域比如“搜索域”“文件域”“数据库域”然后只把该域的工具注入上下文。这样每次模型看到的工具可能只有 8 到 12 个。方案二元工具Meta Tool。给模型一个list_tools(category)工具让它先查询某类别下有哪些工具再决定调用。这种方式更灵活但多了一次往返。在 Spring AI 里工具分组可以通过自定义ToolCallbackResolver实现按当前会话的上下文动态返回工具集合。LangChain4j 里则可以用ToolProvider动态提供工具列表。核心思想一致不要让模型一次看到全部。3.2 按需注入会话级工具裁剪分层是空间维度的治理按需注入是时间维度的治理。一个会话开始时用户可能只是问“帮我查下这个接口的返回”那这个会话根本不需要文件写入、邮件发送这些工具。根据会话意图动态裁剪工具集能大幅降低噪声。实现上可以在会话初始化时做一次意图分类或者让用户显式选择场景。比如一个“代码助手”场景只挂载代码相关工具一个“数据分析”场景只挂载 SQL 和图表工具。Spring AI 的ChatClient支持在每次请求时传入不同的ToolCallback列表这给按需注入提供了天然支持。3.3 动态发现MCP 场景下的工具筛选MCP 场景下工具是动态注册的治理难度更大。我的做法是加一层工具注册中心所有 MCP Server 暴露的工具先注册到中心中心负责去重语义重复的工具只保留一个。打标给每个工具打上类别、优先级、适用场景标签。过滤根据当前会话策略只把符合条件的工具下发给模型。mcp server本身不负责治理治理必须在上层做。这一点很多人没意识到以为接了 MCP 就万事大吉结果工具越接越多Agent 越来越傻。4. Java 生态实操Spring AI 与 LangChain4j 的工具治理4.1 Spring AI 里的工具注册与裁剪Spring AI 的工具调用核心是ToolCallback。默认情况下你通过.tools(...)注册的工具会全部暴露给模型。要治理就得在注册环节做文章。一个实用的模式是场景化工具包public enum AgentScene { CODE_ASSIST, DATA_ANALYSIS, WEB_RESEARCH } public class ToolRegistry { private final MapAgentScene, ListToolCallback sceneTools; public ListToolCallback toolsFor(AgentScene scene) { return sceneTools.getOrDefault(scene, List.of()); } }然后在构建 ChatClient 时按场景取工具ChatClient client ChatClient.builder(chatModel) .defaultTools(toolRegistry.toolsFor(currentScene)) .build();这样每个场景下的工具数量可控。实测下来把六十个工具拆成四个场景每个场景 10 到 15 个工具选择准确率能从 55% 拉回到 85% 以上。注意Spring AI 不同版本 API 有差异defaultTools和tools的行为要对照你用的版本文档确认。spring ai 2.0在工具管理上做了不少改进建议优先用新版本。4.2 LangChain4j 的动态工具提供LangChain4j 的思路略有不同它用ToolSpecification描述工具通过ToolProvider动态提供。动态提供的价值在于工具列表可以在运行时根据上下文变化。ToolProvider dynamicProvider request - { String userQuery request.userMessage().text(); if (userQuery.contains(数据库) || userQuery.contains(SQL)) { return sqlTools; } return generalTools; };这种写法让工具集随用户输入变化天然实现了按需注入。langchain4j rag场景里特别有用——检索相关工具只在需要检索时才挂载。4.3 MCP 工具在 Java 侧的接入与过滤MCP 协议让 Java 应用可以接入外部工具服务。接入本身不难难的是接入后的过滤。我的建议是MCP 接入层和工具治理层分离。MCP 负责“拿到工具”治理层负责“决定给模型哪些工具”。一个典型的过滤策略表过滤维度策略目的类别只保留当前场景类别降低噪声优先级低优先级工具延迟加载减少上下文占用使用频率冷门工具折叠聚焦高频语义重复保留描述最清晰的一个消除歧义权限按用户角色过滤安全合规这套策略落地后六十个工具在单次请求里实际暴露的可能只有 10 个左右Agent 的“选择困难症”自然缓解。5. 工具描述怎么写模型才不迷糊5.1 描述三要素做什么、什么时候用、参数怎么填工具数量治理是一方面单个工具描述的质量是另一方面。我见过太多工具描述写成“查询数据”“执行操作”这种废话模型看了等于没看。一个好的工具描述应该包含三要素做什么一句话说清功能边界。什么时候用明确适用场景和不适用场景。参数怎么填每个参数的含义、格式、示例。举个例子对比两种写法差的写法name: search description: 搜索信息好的写法name: search_web_pages description: 在公开网页中搜索指定关键词返回标题和摘要。 适用于查找最新资讯、事实核查。不适用于查询内部数据库。 参数 query 为搜索关键词建议 3-8 个词。后者让模型一眼就知道边界不会和“查询内部数据库”的工具混淆。5.2 命名规范动词 对象 限定工具命名也有讲究。我推荐动词 对象 限定的结构比如search_web_pages、query_user_table、write_local_file。避免用do、handle、process这种万能动词也避免纯名词。命名的一致性同样重要。如果有的工具用驼峰有的用下划线模型在匹配时容易出错。统一风格统一前缀能显著降低误选率。5.3 参数 schema 的陷阱参数 schema 里最常见的坑是可选参数太多和类型模糊。一个工具有八个可选参数模型很难判断该填哪几个。我的经验是必填参数控制在三个以内可选参数能砍就砍。如果确实需要复杂参数考虑拆成多个工具或者用嵌套对象加清晰示例。类型模糊也很要命。比如一个参数叫time是时间戳还是日期字符串是秒还是毫秒这些必须在 description 里写死最好给示例值。6. 常见问题与排查技巧实录6.1 工具选择错误的排查路径Agent 调错工具时别急着怪模型。按这个顺序排查看工具描述是否重叠把被误选的两个工具描述放一起如果连你都分不清模型更分不清。看工具数量当前上下文里有多少工具超过 20 个就要警惕。看参数 schema是不是参数名太像导致混淆看用户输入是不是输入本身就有歧义看模型换一个模型对比排除模型能力问题。6.2 常见问题速查表现象可能原因解决方向该调工具却不调工具描述没覆盖该意图补充适用场景描述调了错误的工具工具描述语义重叠合并或重写描述参数填错schema 不清晰加示例、收紧类型响应特别慢工具太多占上下文分层、按需注入偶尔正常偶尔错上下文长度波动固定工具集大小工具调用死循环工具返回结果不明确规范返回值格式6.3 独家避坑经验几个我踩过的坑分享出来省得你重蹈覆辙别在工具返回值里塞大段文本。工具返回的内容也会进上下文返回一个几万字的网页全文直接把上下文撑爆。返回摘要或结构化数据。工具报错信息要友好。模型看到“Error 500”不知道怎么办看到“参数 query 不能为空请提供搜索关键词”就知道怎么修。给工具加超时和重试上限。Agent 有时会反复调同一个失败的工具加个熔断机制。定期做工具审计。每季度过一遍工具列表删掉没人用的合并重复的。工具治理是持续工作不是一次性任务。7. 从六十到十一次真实的工具瘦身记录最后分享一个我实际做过的工具瘦身案例。一个内部知识助手项目最初接了 58 个工具包括搜索、数据库、文件、邮件、日历、地图、代码执行等。上线后用户反馈“答非所问”“经常调错工具”。我的处理步骤第一步统计工具调用日志找出实际被调用的工具。结果发现 58 个工具里只有 14 个被真正调用过其余 44 个几乎零调用。第二步按场景分组。把 14 个高频工具分成“检索类”“数据类”“操作类”三组每组 4 到 5 个。第三步重写描述。把语义重叠的工具合并比如三个搜索工具合并成一个用参数区分搜索范围。第四步按需注入。根据用户问题类型只挂载对应组的工具。瘦身后单次请求暴露的工具从 58 个降到 5 到 8 个工具选择准确率从不到 60% 提升到 90% 以上响应延迟也明显下降。用户反馈从“答非所问”变成了“还挺准”。这个案例说明一个朴素的道理Agent 的能力不取决于你给了它多少工具而取决于它能不能在对的时候用对的工具。六十个工具不是能力是负担。把工具治理好十个工具能发挥出六十个都达不到的效果。如果你现在手里的 Agent 也正被工具过载困扰不妨先做一件事把工具调用日志拉出来看看哪些工具真的在被用。大概率你会发现真正重要的工具一只手数得过来。