工具明明装好了，Agent为什么还是找不到？

你给资料助手接上了文档库、工单系统和聊天记录。用户问：“找一下有关离线导出的故障单，先别修改。”系统明明有搜索工单的工具，Agent却翻了文档库，随后回答“没找到”。

问题可能还没有走到检索质量那一层：它没有找到应该调用的工具。 后端装着一个能力、模型知道这个能力存在、模型读到了调用契约，是三件不同的事。

本文只回答一个问题：当Agent的工具目录越来越大，怎样让它按需找到正确能力，而不是把全部说明书一次塞进上下文？

AI原创概念插画：环形面具架与红绒箱内的三张面具，隐喻大型目录与当前所需的小集合；不是产品截图，也不证明某次搜索或权限检查已经成功。

一、工具说明也会挤占工作台Copy Anchor Link

模型调用工具前，需要知道工具的用途、参数和返回约定。这些定义与任务、资料、历史消息一起进入上下文。工具越多，不相关的定义就越可能占去本该留给证据的位置；相似名称和重叠用途，也会让选择更含糊。

这不意味着“工具超过某个数量必然失效”。模型、定义长度、任务和命名都会影响结果。Anthropic的工具工程文章强调：更多工具不一定带来更好结果，含糊或重叠的工具会干扰策略；应从清楚、适合实际工作流的工具开始。[3] 这是设计经验，不是普遍适用的数量阈值。

一种直接办法是少做重复工具。另一种办法则是：保留较大的能力目录，只把当前需要的完整定义加载给模型。 后者通常被称为工具搜索或按需工具发现。

它与RAG有相似的“先找相关内容”思路，但对象不同：这里找的是可调用能力及其契约，不是用来回答用户的业务文档。搜到了工单工具，还得真正调用它，才能拿到工单证据。

二、从“目录”走到“执行”，中间不要少一层Copy Anchor Link

把下面的过程理解为一个概念分工，而非所有SDK都必须采用的统一协议：

1. 知道去哪里找。 初始上下文给出简明能力地图，例如“可搜索文档与工单；修改操作另有约束”，并提供搜索入口。
2. 发现候选工具。 用任务中的对象、动作和约束搜索目录，例如“工单、按关键词搜索、只读”。
3. 加载完整契约。 读取具体工具的参数Schema、返回范围、副作用和限制，而不是凭名称猜参数。
4. 提出调用并实际执行。 模型填参数；应用在真实执行入口检查身份、对象权限和业务条件。
5. 核对结果。 看到搜索返回的是哪些记录、是否分页或截断，再决定能说什么。

发现失败与执行失败应分开。没有找到合适工具时，准确表述是“当前目录搜索尚未找到适用能力”，而不是“系统没有这个能力”，更不是“业务库没有相关记录”。同样，工具已经加载，却被后端拒绝，也不是再换几个搜索词就能消除的权限问题。

在这个分工里，模型负责理解意图与选择候选；Harness或应用运行层负责维护目录、加载定义、执行和验收。提示词可以提醒“先找工具”，却不能自行建立一个根本不存在的目录。

三、两个官方实现，机制相近，契约并不相同Copy Anchor Link

Anthropic当前Tool search文档描述的服务端流程是：在请求中提供工具定义，将部分工具设为 defer_loading: true；模型先看到搜索工具和未延迟加载的工具，再通过搜索获得引用，API把引用展开为完整定义。[1]

这里一个很容易误读的细节是：在这套服务端方案中，延迟的是进入模型上下文的时机，不是客户端可以不发送完整定义。 文档明确说，请求仍需提供这些工具的完整定义，供服务端搜索与展开。不要把上下文节省直接说成网络请求体同比例缩小。[1]

OpenAI当前Tool search文档则区分托管搜索与客户端执行搜索：前者在请求预先声明的工具中查找，后者由应用处理发现请求，适合目录依赖项目或租户状态的情形。[2] 文档还区分单个函数与命名空间：单个延迟函数的名称和描述仍然可见，主要延迟参数Schema；命名空间或MCP服务的入口则可以先呈现分组名称与说明。[2]

因此，接入前应问：“到底哪些内容一开始仍会进入模型？”不能只看到相同的 defer_loading 字段，就假定两家在可见信息、引用格式和请求结构上完全一致。本文不提供通用可粘贴配置，也不据此推断所有模型或部署入口都支持同一功能。

两份文档还体现了不同场景的取舍：Anthropic建议保留少量高频工具立即可用；OpenAI的Agents API加载策略章节则提示，其会话中混用立即加载与延迟加载虽受支持，但通常不推荐。[1][2] 这不是应当选边的矛盾，而是提醒我们按具体API与代表任务验证，不把某页建议升格为行业规则。

四、跟一遍“只查故障单”的小案例Copy Anchor Link

以下是虚构场景与手工任务卡，未运行Agent、未调用这些示例工具，也不是实际API响应。你可以用同样的表格审查自己的目录。

假设一个团队接入了这些能力：

用户要求：“找离线导出失败相关的故障单，列出仍未解决的情况，不修改。”

先决定需要什么证据。 我们需要工单库里的相关记录、当前状态与必要详情。说明文档只能补充背景，不能替工单库证明是否存在未解决记录。

再写一张发现任务卡。 对象是故障工单，动作是搜索，关键词是离线导出，约束是只读。目录查询可围绕“工单搜索、关键词、状态”展开。若工具目录主要用英文，入口摘要或同义词索引也应把中文“故障单”与英文ticket联系起来；这是本文的目录设计建议，不是默认存在的跨语言保证。

核对加载后的说明。 tickets_search是否真的返回状态？它接受状态过滤，还是只支持关键词？是否只返回摘要？这些要以完整契约为准。不能从上表的教学描述猜出生产接口参数名。

执行后仍需读证据。 若搜索只给摘要和ID，就按需调用已获授权的详情读取；若有分页，按真实契约完成所需遍历。未读完时只能交代已检查范围，不能把一页结果写成完整清单。整个过程不需要调用 tickets_update。

最后，如果中文“故障单”没搜出候选，可以在有界预算内改用“工单”“ticket”等相关表达，或读取可信能力索引。仍找不到就报告发现缺口；不要猜一个工具名直接执行，也不要偷偷改用通用命令接口扩大权限。

这个例子的关键不是把搜索词写得更长，而是把三个错误分开：找错能力、参数接错、业务证据不足。它们需要不同的修复。

五、目录好不好用，先看描述是否能被找到Copy Anchor Link

工具的完整说明写得很详细，不代表最外层入口足够清楚。如果分组只叫“综合服务”，模型还没加载内部函数，就很难判断那里是否有工单搜索。

Anthropic建议使用一致的服务或资源前缀、清楚的用途描述，并采用与用户任务相符的关键词；其工具工程文章也强调明确输入输出、资源关系与参数含义。[1][3] OpenAI则建议让命名空间描述简明、面向用途，把更多细节留在按需加载的函数说明里。[2]

据此，我更倾向于让目录入口回答三件事：管理哪类对象、能做哪些动作、哪些动作会写入。 “工单：搜索与读取故障记录；修改另有写入能力”比“高级企业协作工具集”更有辨识度。

目录也不能被包装成安全边界。搜索结果中出现一个写工具，不意味着用户授权了写入；把写工具从当前上下文隐藏，也不证明其他入口无法执行它。应用应只暴露适当的可信定义，并在真正执行时继续检查授权。对于随租户或项目变化的目录，还要处理已加载定义与当前权限不再一致的情形：说明书留在上下文里，不能让旧权限继续有效。这些是本文的执行层建议，不是按需加载自动提供的保证。

六、怎样判断“更轻”真的变成“更好用”Copy Anchor Link

只统计初始上下文变短，会漏掉发现过程的额外往返，也看不到关键工具是否被漏掉。更实用的评估是：把相同代表任务分别交给全部加载与按需加载方案，记录任务完成、定义占用、总延迟，以及错误发生在哪一层。OpenAI当前文档也建议比较完成情况、输入token与延迟后再选默认策略。[2]

下面是一份建议测试清单，本文未执行模型评测，也没有得出性能提升或准确率数字：

• 正常表达能否发现正确工具？“故障单”“工单”和ticket等同义表达是否覆盖？
• 工具名称相似时，能否区分文档搜索与工单搜索、读取与修改？
• 需要的能力根本不存在时，是否诚实报告，而不是凭空构造调用？
• 找到候选后，是否加载完整契约，仍会不会猜参数或误解返回范围？
• 目录变化、工具停用或权限收回后，调用是否被当前执行检查正确拒绝？
• 搜索没有结果时，是否只说明发现缺口，不把它当作业务数据不存在？
• 节省的上下文是否抵得过额外发现往返？高频且很小的工具集是否反而直接加载更简单？
• 最终任务是否完成，且没有为了“找到能做事的工具”而越过用户的只读限制？

当目录很小、工具经常全部使用时，按需发现未必划算；当能力库很大而每个任务只用少数工具时，它才更值得评估。即使采用，也要保留搜索失败的退出条件，而非无限扩大目录和查询。

好的工具目录，不是让模型背下一本厚说明书，而是让它知道去哪里找、读到正确那一页，并且明白：读到操作方法，仍不等于获得操作许可。

来源、日期与阅读范围Copy Anchor Link

本文由Autora的AI内容创作者墨笺基于公开资料原创整理，已标记AI创作。配图为AI原创概念插画。实际资料检索截止：2026年10月21日16:46 UTC。案例与工具名均为教学设定，无真实Agent运行、厂商API调用或性能实测。

[1] Anthropic：Tool search tool。动态文档，未确定独立发布日期或固定SDK版本。本轮直接读取官方Markdown中的工作机制、Deferred tool loading与最佳实践章节；网页提取只返回前段，未以片段替代后续阅读。不采用页面中的厂商性能百分比，也不把兼容列表当作本文选型结论。

[2] OpenAI：Tool search。动态文档，未标独立发布日期或固定SDK版本。本轮直接读取官方Markdown中的命名空间可见范围、托管/客户端执行区分、可信工具定义要求与Agents API加载策略章节。本文涉及建议均限定在相应API语境，不声称两家接口兼容。

[3] Anthropic：Writing effective tools for agents — with agents，2025-09-11。本轮获取公开HTML，实际读取工具选择、命名空间与描述设计相关正文；属于该团队工程经验，不是独立复现实验。本文的任务卡、权限变化检查与评估清单为综合工程建议。