# 给 Agent 接上 80 个工具，它更容易选错

> 少数核心工具常驻上下文，其余按统一前缀分组，任务需要时再让 Agent 搜索。

原文: https://fdetimes.net/zh/guides/tool-search-for-agents-with-many-tools/

你刚把客户的 Agent 接入了六个 MCP 服务器：GitHub、Slack、Jira、CRM、仓储系统和计费系统。演示一切正常。可再数一遍，Agent 手里已经有 80 个工具，试点用户也开始抱怨：问它“有哪些未关闭的工单”，它却新建了一张工单。

改系统提示词很难从根本上解决这个问题，因为症结多半在于 Agent 一次要看的工具太多。Anthropic 关于工具搜索的文档写得很明确：工具数量超过约 30–50 个后，Claude 选对工具的能力就会下降。80 个工具，已经深入危险区。

这里需要的能力，是设计 Agent 如何看到工具：哪些始终可见，哪些分组，哪些只在需要时加载。做得好的前线部署工程师（FDE）能同时降低成本、提高准确率，而不是一句一句地给系统提示词打补丁。

## 八十个工具，代价在哪里？

第一项代价是 token。Anthropic 举过一个例子：一套配置接了五个 MCP 服务器、58 个工具，对话开始前，光是工具定义就占了约 55K token。该公司还表示，见过优化前工具定义消耗 134K token 的情况。

算一笔账：55K 除以 58，平均每个工具约 950 token。如果客户的工具长度相近，80 个工具大约要占 76K token。这只是粗略估算，但足以说明：用户还没说第一句话，上下文就已经用掉了一大块。

第二项代价更大：准确率。据 Anthropic 介绍，工具集很大时最常见的两类失败是选错工具和传错参数。当 `jira_search_issues` 和 `jira_create_issue` 与另外 78 个工具并列时，两者的界限就模糊了，这正是试点用户遇到的 bug。

## 先分组，再延迟加载

核心思路很简单：Agent 不需要一次看到所有工具，只需要在合适的时刻找到合适的工具。Anthropic 的建议是让最常用的三到五个工具始终加载，其余延迟加载。

**要点:** Agent 不需要一次看到所有工具，只需要在工作需要时找到对的那一个。

但延迟加载的前提是 Agent 能把工具找回来，所以必须先分组。Claude 的文档建议按服务或资源，用统一前缀给工具命名，比如 `github_` 或 `slack_`，这样一次搜索就能匹配整组工具。文档还建议在系统提示词里列出各个工具组。

OpenAI 的做法类似：它的工具搜索动态加载工具，并建议按命名空间或 MCP 服务器给工具分组。它还给了一个具体数字：每个命名空间少于 10 个函数，既省 token，也有助于模型表现更好。

## 实例：一家物流公司的运营 Agent

回到那 80 个工具。第一步，和真实用户坐下来，问清楚他们每天最常做什么。假设答案是查订单、查货运状态、找工单、在值班 Slack 频道发消息。这四个工具就是常驻的核心。

剩下 76 个工具。如果每组少于 10 个，也就是最多 9 个，简单做个除法就知道至少需要 9 组，因为 8 组最多只能容纳 72 个工具。

实际操作中，可以先分出 `github_`、`slack_`、`jira_`、`crm_` 和 `billing_`，再把庞大的仓储系统拆成 `warehouse_inventory_`、`warehouse_inbound_`、`warehouse_outbound_` 和 `warehouse_returns_`。哪一组仍超过 9 个工具，就按资源继续拆分。

一个延迟加载的工具如下所示。注意带前缀的名称，以及清楚说明何时使用的描述：

```json
{
  "name": "warehouse_inbound_list_delayed_receipts",
  "description": "列出晚于计划的仓库入库单，可按仓库和日期范围筛选。用户询问货物迟到时使用。",
  "input_schema": {
    "type": "object",
    "properties": {
      "warehouse_id": { "type": "string" },
      "from_date": { "type": "string", "format": "date" }
    },
    "required": ["warehouse_id"]
  },
  "defer_loading": true
}
```

在系统提示词中加一小段，列出各个工具组，例如：“工具按前缀分组：warehouse_inbound_ 用于入库货物，billing_ 用于发票……”。用户问起迟到的货物时，Agent 就知道去搜索 `warehouse_inbound`，一次搜索就能拿回整组工具。

## Agent 怎样找到工具？

Claude 提供两种服务端搜索方式：regex 和 BM25。入门的实用建议是：如果工具名已经严格遵循前缀，就像上面的例子，先试 regex，因为 `warehouse_inbound_.*` 这样的模式能匹配整组工具。

如果用户习惯用自然语言提问，也试试 BM25，让评测集决定哪种方式选对工具的比例更高。

如果客户有很多含义相同、名称不同的工具，可以自己写搜索逻辑，比如用嵌入或语义搜索，再从自定义工具中返回 `tool_reference` 块。这个方案留到 regex 和 BM25 在评测集上都失败之后再用，不要一开始就上。

上生产环境时，别忘了提示词缓存。OpenAI 把新找到的工具加载到上下文窗口的末尾，这样请求之间的提示词缓存不会失效。这条经验普遍适用：让上下文开头部分，也就是系统提示词和核心工具，保持稳定，不要在调用之间调整顺序。

## 常见错误

最常见的错误是以为 `defer_loading` 能让请求变轻。Claude 的文档说得很清楚：每次请求仍须在 `tools` 数组中发送每个工具的完整定义，包括延迟加载的工具。这个标志只决定哪些内容进入上下文窗口，因为 API 需要全部定义才能搜索和展开它们。

第二个错误是给每个 Agent 都用上工具搜索。文档指出，工具搜索适用于工具数在 10 个及以上，或定义超过 10k token 的场景。工具少于 10 个，或者每次请求都会用到所有工具时，普通的工具调用效果更好。小客户只有六个工具的 Agent，不需要额外的搜索层。

第三个错误是连核心工具也延迟加载，让 Agent 连一小时要做十次的事都得先搜索。第四个错误是随意命名，比如 `getData2` 或 `helper_sync`，这会让任何基于名称的搜索失效。

## 用数据证明

不要跟客户说 Agent“更聪明了”，要去衡量。在 Anthropic 内部的 MCP 评测中，启用 Tool Search Tool 后，Opus 4 从 49% 提升到 74%，Opus 4.5 从 79.5% 提升到 88.1%。Anthropic 还表示，工具搜索能把 token 用量减少 85%，同时保留对完整工具库的访问。

你的数字会不一样，因为客户的数据和工具不一样。整理一组真实请求，为每条记录正确的工具和正确的参数，然后分别统计 Anthropic 提到的两类失败：选错工具和传错参数。在改造前后跑同一组请求。

这个结果也能成为简历上很有分量的一行，例如：“借助工具搜索，将 80 个工具重构为 4 个核心工具和 9 个带前缀的工具组，工具定义 token 从 X 降至 Y，在 N 条请求的评测集上，工具选择正确率从 A 提升到 B”。

这样一行字说明你衡量的是结果，而不只是描述做了什么。

## 在自己的 Agent 上练手

练习：拿一个现成的 Agent，或者新搭一个接入两三个公开 MCP 服务器的 Agent。打印完整的工具列表，标出你认为属于核心的 3–5 个工具，再把其余工具分成带前缀的组，每组最多 9 个。

接着，按真实用户的口吻写 20 条请求，为每条记录正确的工具和参数。先在旧配置上跑一遍，再在启用 `defer_loading` 的新配置上跑一遍，分别统计选错工具和传错参数的次数。如果某个组总是匹配错误，说明它的名称或描述需要重写。

下次客户想接入第七个系统时，第一个问题不该是能不能接，而是新工具归入哪一组、Agent 将如何找到它们。

**本周动手试试:**

- 打开手头的 Agent，数一数工具数量，估算全部工具定义在上下文中占用多少 token
- 写 20 条真实用户请求，为每条记录正确的工具，然后运行，看 Agent 选错工具或传错参数的频率
- 用系统前缀重命名工具，选出 3–5 个核心工具，其余延迟加载，再原样重跑这 20 条请求

## 信源

- [Introducing advanced tool use for Claude | Anthropic](https://www.anthropic.com/engineering/advanced-tool-use)

- [Tool search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool)

- [Tool search | OpenAI API](https://developers.openai.com/api/docs/guides/tools-tool-search)
