本文是「Agent 工程实战」系列的第 18 篇属于工具链线。系列索引21 篇阅读路线Agent 放权前先补权限、出站、发现这三道口子摘要把 MCP Server 对接 OpenAI Agents API 的一次对照推演中Agent 全程没调用工具却输出了一份很自信的答案。根因不在 Server 挂了而在工具描述在按需加载机制下没被选中。用一次对照讲清工具描述写法的变化。文章目录它没碰工具还给我交了份作业现象答案挺自信日志里空空如也排查不是连不上是没被选上根因描述写得泛检索的时候选不中解决描述写到这个工具什么时候会被需要想复现的话实验步骤在这边界这套改动在哪些情况下不灵总结判断它没碰工具还给我交了份作业上一篇把 MCP Server 怎么接进 OpenAI Agents API 盘了一遍临走前我留了个话头工具描述在按需加载的世界里评价尺度变了。写完之后我琢磨光说不够得拿自己的 MCP Server 做一次对照。先把话说清楚我目前没有 OpenAI Agents API 的接入环境下面这次对照是把官方文档里的机制和自己本地 MCP 测试台的观察摆在一起推演的。真实的部分——本地测试台里 agent 用不用我的工具——是我反复跑过的推演的部分——换到 Agents API 上会发生什么——我会标出来不混着说。机制描述基于 2026.09.10 发布的公开测试版文档接口还在迭代你看到时如有变动以官方为准。这个测试台就是写 MCP Client 那篇时搭的一个带工具调用能力的 agent 客户端挂上我的 MCP Server任务丢进去能直接看到它到底调不调工具。下面的观察都发生在这里。对照任务我选了个很朴素的查一个订单的发货状态。这任务有个好处正经答案只存在于工具里agent 不调工具就只能编。编得好不好一对比就现形。现象答案挺自信日志里空空如也任务丢下去agent 回来的东西长这样本地测试台里的真实复现订单已发货预计 3 天后送达承运方顺丰当前物流节点为运输中。看着像那么回事。我去翻 agent 的工具调用记录一条调用都没有——它从头到尾没用过我的 MCP 工具。如果是真实环境这只是运气好级别的胡编送达时间、承运方、物流节点全是我系统里查无实据的数据。它根本没查它是在凭常识写一份体面的快递播报。问题就来了Server 在本地跑着明明好好的地址能通工具列表也能拉出来这串列表是我自己用 MCP 客户端拉出来的不是 agent 拉的。为什么 agent 一个都没用把这个疑问摆到 Agents API 的 tool search 机制里看链路是这么推出来的推演部分Agent 要查订单发货状态 │ ▼ Agent 需要订单信息 ──► tool search 按需加载候选工具 │ │ │ ▼ │ query_orders(处理订单数据) │ ── 描述太泛需要的时刻没被选中 │ │ ▼ ▼ Agent 拿不到工具结果 ────────► 改用常识直接编答案 │ ▼ 一份自信且查无实据的物流播报排查不是连不上是没被选上排查按三步走每一步都有明确结论轮次怀疑点动作结果第一轮连接失败翻 agent 的工具调用记录任务跑完调用记录为零——压根没调用过第二轮配置有误核对 agent 里的 server_label 和 server_url配置正确、地址可达第三轮加载机制对照官方文档 tool search 的原话按需加载——问题出在该加载时没选我第二轮有个容易被忽略的细节配置正确并不代表被使用。server_label只是标识哪台 serveragent 用不用它取决于工具有没有进入自己的视野。很多人排查到这里就停了以为是玄学其实方向在第三轮。官方文档里 tool search 的说法是按需加载相关的工具定义省 token、保持缓存命中原文档。我读到的重点是按需——agent 不会把你的工具全搬进上下文它需要的时候选一批进来。我的工具没被调用是因为连被选这一关都没过。根因描述写得泛检索的时候选不中问题定位到我 Server 里那个查订单工具的描述。为什么要看这段它是这次事故里唯一的嫌疑人——同一台 Server、同一个地址唯一被质疑的就是这串描述这是改前的样子{name:query_orders,description:处理订单数据,inputSchema:{orderId:string}}把它放回本地测试台触发同一种查询任务观察到的调用情况是这样的本地观测// 触发任务这个订单发到哪了 // 可用工具列表里 query_orders 一直在 // 但任务跑完没有产生一次对 query_orders 的调用 // 输出是 agent 直接给出的常识性回答问题就藏在这串描述里。面对这个订单到哪了的问题agent 要走检索我的描述是处理订单数据——词太宽了任何订单类任务都能沾边但都不精准。在按需加载的过程里它可能被更具体的同类工具顶掉也可能被归进通用数据处理一类需要它的时候没被选中。这里要严谨一点官方没公开检索内部是关键词还是语义匹配我不确定机制细节。但方向是确定的——官方机制就是按需加载而我的工具在按需这一环就落了榜。解决描述写到这个工具什么时候会被需要重写之后长这样{name:query_order_shipping_status,description:按订单号查询订单发货状态返回预计送达时间,inputSchema:{orderId:{type:string,description:订单号必填}}}为什么要看这段同样的底层逻辑我把名字和描述从它是什么改成了什么场景会用上它。描述里带上了发货状态、预计送达时间、订单号这些和查询任务强相关的词按需加载时被选中的概率会高很多——就像给检索器递了个正好能挂住问题的钩子。改完我在本地测试台验证了同批任务结果差异是实实在在的这部分是本地观测改前描述query_orders / 处理订单数据 → 任务查订单发到哪了agent 跳过工具直接给了个编造的时间 → 日志无工具调用 改后描述query_order_shipping_status / 按订单号查发货状态 → 同一任务agent 先调工具拿到数据再基于数据作答 → 日志出现该工具的调用记录对比放在一起看更清楚改前改后namequery_ordersquery_order_shipping_statusdescription处理订单数据按订单号查询订单发货状态返回预计送达时间面对查发货状态任务很像通用数据处理大概率没被选中与问题强相关可用性一眼可见本地测试台效果经常跳过工具直接编基本先调工具再作答想复现的话实验步骤在这这套对照实验不依赖 Agents API 的接入权限用你手头的 MCP 工具链就能跑步骤不长准备一个 MCP Server没有的话拿官方示例改一个也行注册一个查订单类工具挂一个带工具调用能力的 agent 客户端我用的就是写 MCP Client 那篇搭的测试台先用泛描述query_orders / 处理订单数据跑这个订单发到哪了看调用日志改成具体描述query_order_shipping_status / 按订单号查询发货状态同一个任务再跑一遍对比两次日志里的工具调用次数判断标准很简单改前大概率零调用、直接作答改后出现工具调用、结果基于数据。如果两次没有差异先检查 agent 客户端是不是把工具全量塞进了上下文——那样就绕过了按需加载这一步对照就失效了。边界这套改动在哪些情况下不灵别把这篇的经验用过头几个边界先讲清楚推演建立在按需加载是主要路径的假设上。官方文档Agents API overview提到可以挂自定义函数和内置工具也保留了程序化调用的能力不是所有场景都走检索选中这一步。描述写得具体是有代价的越具体描述串越长和省 token的目标就互相拉扯得在够具体和别啰嗦之间找平衡没有标准答案。我没在真实的 Agents API 上复现完整链路没有接入环境所以改描述后必然命中这个结论在你们真实环境里仍然要自己验一遍。工具是否被选中还取决于任务描述、上下文和候选池大小这些变量。总结判断这次对照给我的触动不是描述要写具体——这我早就知道了。新东西是工具描述不只是在给 agent 的理解供料现在多了一层是在给检索供料。写得泛等于把选择权交给运气写到任务场景上去才是主动递给 agent 钩子。给同样在把 MCP 接进 agent 的人一句你磨参数 schema 的功夫已经够了接下来值得把一半的精心放在 description 上——那是 agent 决定用不用你的第一道门。MCP 协议本身的细节可以看 modelcontextprotocol.io。真要在自己环境里接开工前对着这三条过一遍任务是不是真的依赖工具才有答案不依赖的话agent 不调用工具不算 bug工具描述是不是写到什么场景会用到它泛描述在按需加载下风险最高有没有在能复现的测试环境里验过一遍我没有真实接入结论需要你自己复验「Agent 工程实战」系列路线工具链线MCP/测试脚本上一篇17 MCP 写进官方示例下一篇19 MCP 安全四件事系列索引21 篇阅读路线Agent 放权前先补权限、出站、发现这三道口子专栏Agent 工程实战如果这篇对你有用欢迎收藏想追更可以关注「Agent 工程实战」专栏。