改写工具说明书：你的 Agent 调用老翻车，问题可能不在模型，在那段给人看的文档

我先说一个可能会冒犯很多人的观点：你的 Agent 调用工具老出错，十有八九不是模型不够聪明，而是你喂给它的那段工具说明书，本来就是写给人看的。

这话听起来有点像甩锅。模型那么贵、参数那么大、跑分那么高，怎么会栽在一段文档上？

但你冷静想想：你给 Agent 接了一个天气 API，文档里写着"获取指定地点的天气"。地点怎么传？经纬度还是城市名？城市名要中文还是英文拼音？纬度的合法范围是多少？这些信息，文档全没写——因为当年写这份文档的工程师，默认读它的是另一个工程师，看不懂大不了点开源码翻一翻。

可 Agent 不会翻源码。它只能盯着这段话猜。猜对了,任务完成;猜错了,你在日志里看到一行刺眼的 400 Bad Request,然后开始怀疑是不是该换个更大的模型。

2026 年 2 月,来自 Intuit AI Research 的一篇论文——《Learning to Rewrite Tool Descriptions for Reliable LLM-Agent Tool Use》——把这件事捅破了:与其没完没了地调教 Agent,不如回头把工具的"说明书"重写一遍,改成专门给机器看的版本。他们做出来的方法叫 Trace-Free+,在工具数量飙到 150 个以上时,把"任务成功率"硬生生拉高了 60.89%。

接下来我们就一层层揭开:Agent 调用工具,到底是怎么翻车的?这篇论文又凭什么说,改文档比改模型更划算?

---

一、真凶不是模型，是那段给人看的说明书

我们先把"Agent 调用工具"这件事拆开看。

一个 Agent 要完成"帮我订一张明天去上海的高铁票",它脑子里其实在做三道选择题:第一,我手上有几十上百个工具,该挑哪个?第二,挑中了"购票"这个工具,它要哪些参数?第三,这些参数我该填什么值?

这三步,全靠一样东西支撑——工具描述(tool description)。也就是每个工具配的那段自然语言说明,加上参数的 schema(名字、类型、是否必填)。

问题在于,这些描述几乎全是"人类中心"的。它们诞生于 API 文档,服务对象是写代码的人。人有什么?人有常识、有上下文、有 Stack Overflow、有点开源码的能力。所以文档可以偷懒,可以含糊,可以"你懂的"。

论文作者打了个特别精准的比方:工具描述就是 Agent 和外部世界之间的接口契约。契约写得含糊,再聪明的执行方也会违约。这不是能力问题,是信息问题——你压根没把规则告诉它。

更要命的是规模。当工具只有三五个时,模型还能连蒙带猜。可一旦工具池涨到 100 个、150 个,几十个功能相近的接口摆在一起,描述里那点含糊就会被无限放大。挑错工具、填错参数,像滚雪球一样越滚越大。

所以这篇论文的第一个洞察就特别反直觉:想让 Agent 更可靠,别急着换模型,先去看看你给它的工具说明书,是不是还停留在"给人看"的年代。

二、五种"坑"：工具说明书到底差在哪

光说"文档写得烂"太虚了。这篇论文最扎实的地方,是把"烂"拆成了五种具体的、可复现的坑。我们一个个看,你会发现每一个都似曾相识。

坑一:不知道什么时候该用它(工具选择边界)。描述只说了这个工具"能干什么",没说它"什么时候不该用"。结果两个功能相似的接口摆在一起,Agent 反复横跳,选错了还浑然不觉。

坑二:参数格式没说清(参数约束)。这是重灾区。论文里举了一个 Walk Score API 的例子:它要一个纬度参数,但文档没告诉你纬度的合法范围是 -90 到 90;它还有个"是否计算骑行得分"的参数,文档没说这里必须传字符串 '1',而不是布尔值 true。Agent 想当然填了个 true,接口直接报错。

坑三:不知道参数从哪来(跨工具依赖)。真实任务很少是单个工具搞定的。比如先调"搜索电影"拿到一个 movie_id,再用这个 id 去调"获取演员表"。但文档常常不写:这个 id 参数,得是上一个工具的输出。Agent 不知道,只能凭空捏一个,然后……你懂的。

坑四:不知道它会吐回来什么(输出描述缺失)。调完一个工具,它返回的是什么?有哪些字段?类型是什么?如果描述不说,Agent 就没法把这一步的输出,接到下一步的输入上。链条还是断。

坑五:参数之间还有暗规则(跨参数依赖)。有些参数是互斥的——填了 A 就不能填 B;有些是成对出现的——要么都填,要么都不填。这种"潜规则"几乎从不写进文档,但违反了就报错。

看完这五条,你大概明白了:这些坑没有一个是"模型笨"造成的。它们全是信息缺失。文档里本该有、却没有的信息,逼着 Agent 去赌。

论文里有一个特别传神的前后对比。有个工具原本的描述是:

"Fetches the year a particular scientific work was published."(获取某部科学著作的出版年份。)

看着没毛病吧?但 Agent 一用就翻车。因为它会把"万有引力定律"这种俗称直接当标题传进去。而这个 API 要的是著作的完整正式标题——《Philosophiæ Naturalis Principia Mathematica》(自然哲学的数学原理)。改写后的描述,会明确告诉 Agent:这里要传完整正式书名,不要传通俗叫法。

你看,改动其实很小——就补了一句话。但对 Agent 来说,这一句话的差别,就是成功和失败的差别。工具描述不是文档,是 Agent 的"操作规程";少写一行,就可能多崩一次。

三、老办法的死胡同：为什么"试一遍再改"行不通

"那简单啊,"你可能会说,"让 Agent 去试,试错了把错误信息记下来,再回头改文档不就行了?"

恭喜,你想到的正是之前主流的做法。学术上有个词叫execution trace(执行轨迹):让 Agent 真刀真枪跑一遍任务,记录下它每一步调了什么、传了什么、报了什么错、最后成没成。然后从这些"踩坑记录"里提炼规律,反过来优化工具描述。

这套思路对不对?对。有用吗?有用。但它有两个要命的前提。

第一,你得先有"试错"的机会。可现实里太多场景压根不允许试。一个刚上线的新工具,没有任何历史调用记录,这叫冷启动(cold-start);一个涉及用户隐私、金融交易的接口,你不可能让 Agent 拿真实数据去反复试,这叫隐私约束。这两种情况下,执行轨迹根本不存在。巧妇难为无米之炊。

第二,这套流程贵得离谱,而且不通用。论文点了名:旧方法要为每一个新工具,从头跑一遍多阶段流水线——合成测试查询、让 Agent 执行、标注轨迹、再用大模型提炼。来一个新工具,整套再来一遍。一个工具一个工具地优化,完全没法规模化。

所以矛盾就摆在这了:执行轨迹里藏着最宝贵的"实战经验",但部署的时候,你恰恰最可能拿不到它。

怎么办?能不能在训练阶段把轨迹的经验榨干,到了部署阶段就彻底不依赖它?

这,就是 Trace-Free+ 这个名字的由来——"Trace-Free",无轨迹。它要的就是:用的时候,不需要任何执行轨迹。

四、Trace-Free+：把"试出来的经验"教成"看一眼就会"

要理解 Trace-Free+ 的巧妙,得先看它"笨"的版本长什么样。

最朴素的想法叫 Trace-Free(没有那个加号):既然部署时拿不到轨迹,那训练时我也不用轨迹,只拿"工具 schema → 好描述"这种干巴巴的样本来教。结果呢?模型确实学会了"无轨迹",但也白白扔掉了执行轨迹里那些最珍贵的实战信号——哪些参数会被填错、哪种格式会报错、哪两个工具容易混。这些金子,全没了。

Trace-Free+ 那个"+",加的就是课程学习(curriculum learning)。这个词听着唬人,其实道理朴素得像你小时候学骑车。

具体怎么走?论文把训练分成了一条由"扶"到"放"的坡道:

• 训练前期(辅助轮阶段):大量喂带执行轨迹的样本。模型在这里看清楚——这个失败是怎么发生的,那个成功又对应了描述里的哪句话。它在学"病例"。
• 训练中期(逐渐撒手):慢慢调高"无轨迹样本"的比例。拐杖一点点抽走,模型被迫开始自己琢磨规律,而不是死记某条轨迹的修法。
• 训练后期(彻底放手):样本几乎全是无轨迹的。模型必须只看一个工具的 schema,就生成出高质量的描述。这时候它学到的,已经不是"某个工具的修法",而是"怎么把任何工具的描述写好"的通用直觉。

这一招的精髓在于:它把成本全压到了离线的训练阶段。模型一旦训好,部署时面对一个全新工具,只需要读 schema,瞬间生成好描述——不跑任务、不要轨迹、不碰隐私数据、推理成本极低。该出的力,在出厂前就出完了。

那训练用的"病例库"从哪来?这是论文另一块硬功夫——他们专门搭了一套数据流水线:

• 第一步,种子工具标注:从 ToolBench 里捞出 5,576 个真实世界的 RESTful API,用一个"智能标注器"判断每个接口是死是活,再切成训练集(991 个工具)和测试集(4,585 个工具)。
• 第二步,带依赖的查询合成:这步是关键。他们分析 API 的真实调用历史,找出工具之间的"前后依赖",再让大模型生成那种必须串起 3 个以上工具才能完成的多步任务。因为只有多步任务,才逼得出"跨工具依赖"这种深层的坑。
• 第三步,两阶段描述改进:先套用一套通用文档规范,得到初版改写(论文里叫 D₁);再结合从轨迹里提炼的规则(用一个叫 RIMRULE 的框架),精修出终版(D₂)。

顺便说一句,负责"写描述"的模型,用的是 Qwen3-4B-Instruct——一个只有 40 亿参数的小模型。这事本身就很有信息量:改写工具描述,不需要动用最顶级的大模型。方法对了,小模型也能干出漂亮活。

五、成绩单：数字到底好看在哪

方法再漂亮,也得拿数字说话。论文在两个公认的硬核基准上做了测试,我挑最能说明问题的几个数给你。

第一个是 StableToolBench,专门考多步任务(G2+G3 这种需要串多个工具的题)。结果是这样的:

工具描述版本	任务成功率	说明
D₀(原始,给人看的)	33.5%	未经改写的人类文档
D₁(通用规范改写)	41.5%	套通用规范的初版
Trace-Free+	44.6%	课程学习生成的终版

从 33.5% 到 44.6%,看着是 11 个百分点,但这是完全没碰 Agent、没换模型的前提下,纯靠改文档拿到的。你想想,这相当于免费给你的 Agent 升了个级。

第二个基准 RestBench(用的是 TMDB 电影数据库)更夸张:原始描述 D₀ 的成功率是 49.5%,Trace-Free+ 直接干到 74.9%——相对提升 51.3%。

但真正让我觉得这篇论文有分量的,是"规模压力测试"。前面说过,工具一多,含糊的描述会被无限放大。论文就专门把工具池撑到 150 个以上,看会发生什么:

这点特别重要。Demo 里挂三五个工具谁都行,可真实的企业 Agent,工具池动辄几十上百。能扛住规模,才是能上生产的硬通货。

还有两个发现我得提一句。一是跨域泛化:在一个领域训出来的描述改写能力,换到没见过的领域,不用重训也照样有效——这正是"学会看病"而非"治一个病"的回报。二是互补性:改写工具描述和微调 Agent 本身,这两条路不打架。你把 Agent 也调好了,再叠加上改写后的描述,还能再涨一截。

所以结论很清楚:改工具描述,不是改模型的"平替",而是一个被长期忽视、却性价比极高的独立杠杆。同样一份算力,与其全砸在模型上,不如分一点给被你冷落多年的那段文档。

六、写在最后：环境工程，才是 Agent 的下半场

我们从头捋一遍这篇论文的逻辑链,其实特别清爽:

• 真问题被找错了:Agent 工具调用翻车,很多时候不是模型笨,是工具描述写给人、没写给机器。
• 坑是具体的:工具选择边界、参数格式、跨工具依赖、输出描述、跨参数依赖——五种信息缺失,每一种都能让多步任务断链。
• 老办法走进死胡同:依赖执行轨迹,可冷启动和隐私场景压根没有轨迹,而且一个工具一套流程,贵且不通用。
• Trace-Free+ 的解法:用课程学习,在训练时榨干轨迹经验,在部署时彻底甩掉轨迹,让小模型学会"看一眼 schema 就把描述改好"的通用直觉。
• 数字够硬:多步任务、超大工具池下,任务成功率最高提升 60.89%,且能跨域泛化、与 Agent 微调互补。

我的判断是:过去两年,所有人的目光都钉在 Agent 的"大脑"上——更强的推理、更长的上下文、更花哨的规划。但这篇论文提醒了一件被严重低估的事:Agent 表现得好不好,一半取决于它生活在一个什么样的"环境"里。而工具描述,就是这个环境最基础的地基。地基歪了,楼盖多高都晃。

我甚至觉得,"环境工程"(Environment Engineering)会和"提示词工程""上下文工程"并列,成为 Agent 时代一个独立的工种。谁的工具接口写得对机器友好,谁的 Agent 就更稳、更省、更能扛规模。

那就大胆做两个预测,给自己设个 deadline:

• 2026 年底之前,主流的 Agent 框架(LangChain、LlamaIndex 这一档)里,会出现专门的"工具描述自动优化"模块——把人写的 API 文档,一键改写成 Agent 友好的版本。
• 2027 年内,"为 Agent 优化的工具接口"会变成 MCP 这类协议的标配关注点,甚至催生专门做"工具描述质量"的工具链和评测榜。

半年后、一年后回来看看,我说得对不对。

但不管预测准不准,有一件事你今天就能做:打开你正在用的那个 Agent,挑一个它最近调错过的工具,去读读那段工具描述——用"机器读者"的眼光读。那五种坑,它占了几条?

我赌你会发现,问题从来不在模型那边。