给 Pi Agent 的扩展装了一堆之后我每次翻请求日志都会皱眉工具提示词占用的 token比真正干活的指令还多。几轮优化下来我把整套工具定义从“自然语言小作文”改成“结构化声明”同一个任务集合实测工具相关 token 直接砍掉 91%任务成功率没降反而因为上下文干净了模型第一步选工具的准确率还稳了一点。这篇就记录整个思路和具体操作Pi Agent 用户想省 token、省预算的可以直接照着改扩展作者想让自己的工具更容易被模型选中、更容易被用户留下也能直接抄后半部分的模板。先说清楚前提。我用的 Pi Agent 配置了 8 个扩展、一共 23 个工具单次任务的基础上下文里工具声明占了将近 4500 token。在长对话场景里这个数字还会被反复带进历史实际开销比单看一次请求更吓人。所以“省掉 91% 的工具提示词”不是标题党是把所有工具声明统一换格式之后算出来的真实降幅。下面从原理到实操一步步讲。1. 先搞清楚工具提示词究竟花在哪了1.1 一次完整工具调用被拆成了四段话很多人不知道工具 token 花在哪是因为平台把工具定义“自动隐藏”了。实际上 Pi Agent 在执行任务时会把所有注册工具的定义序列化后拼进模型上下文模型先读完这一大坨工具说明才轮到读你的指令。单看一个工具它的 token 开销至少有四块工具名和一句话简介。用途详述也就是扩展作者写的那段“本工具适用于……当用户需要……时请调用”的自然语言描述。参数说明每个参数的名称、类型、含义、示例值通常还要跟一段示例。调用演示比如“用户问 X 就传 Y”这种示例句一些认真的扩展作者会写两三条。一个扩展注册 5 到 10 个工具是常态每个工具平均下来 250 token 左右光工具块就是 2000 token 上下。模型还没开始理解你的问题两三千 token 已经花完了。更麻烦的是长对话里每一轮都要把这些定义再带一遍所以它不只是一次性成本而是每一轮都要重复付的“过路费”。1.2 91% 的账是这么算出来的我拿最典型的一个工具search_news举例。它负责按关键词搜新闻、返回标题和来源。旧版声明长这样search_news 工具用于搜索新闻资讯。当用户想要了解最新的新闻动态、某个热点事件的最新进展或者需要按关键词查找相关报道时请使用本工具。参数 keyword 表示要搜索的关键词是一个字符串必填参数 days 表示返回最近几天的新闻默认为 3 天参数 source 可选用于限定新闻来源。示例用户问“最近有什么科技新闻”调用 search_news(keyword“科技”, days7)。如果用户没有指定时间范围就使用默认的 3 天。这一大段按中文分词大概折算 180 到 220 token。改成结构化声明之后是下面这个 JSON{ name: search_news, description: 按关键词检索新闻返回标题、来源和时间, parameters: { keyword: { type: string, required: true }, days: { type: integer, required: false, default: 3 }, source: { type: string, required: false } } }这段 JSON 大概 30 到 40 token。单个工具降幅约 82%。为什么我敢说 91%因为除了描述本身旧格式里每个工具还跟着使用示例和“特殊情况说明”这些在结构版本里全被删掉了。把 23 个工具统一改完工具相关 token 从 4500 出头降到 400 左右降幅正好在 91% 上下。所以 91% 是整套配置的聚合结果不是单个工具的极限值。提示如果你的扩展作者写描述特别啰嗦比如每个工具都带两三个例句单工具降幅能到 95% 以上。改之前先导出一份当前声明用平台日志或离线脚本算一下 baseline后面才知道优化到底有没有用。2. 省 token 的核心思路从“写作文”改成“填表格”2.1 传统写法为什么又长又费工具提示词的膨胀根源在于扩展作者下意识把工具当成“给人看的说明书”来写。人需要前因后果、需要使用场景描述来理解一个工具但模型不一样它吃的是函数调用格式的训练数据。你写“当用户想要了解最新的新闻动态、某个热点事件的最新进展时”这些措辞在模型眼里只是噪音真正的信息只有“按关键词搜新闻”这七个字。还有一个隐藏问题长描述会带来互相矛盾的信号。比如你写了“如果用户没有指定时间范围就使用默认的 3 天”模型可能把它理解成两个动作——先判断有没有指定再决定要不要传参。其实正确做法是把默认值写进default字段模型看到的是“这个参数可以不传”不需要额外推理。传统写法最大的浪费是重复描述。很多扩展作者会在用途详述里把参数含义再解释一遍参数列表里又解释一遍示例里第三遍。同样的信息出现三次token 自然成倍上涨。结构化声明强制你每个信息只写一次重复自然消失。2.2 结构化声明三行抵一段话结构化声明说白了就是 JSON Schema 那一套也是现代模型最熟悉的函数调用格式。核心字段就四个name工具名保持简短最好一眼能看出职责。description一句话说清“做什么 什么时候用”这是模型判断要不要调用你的关键。parameters参数字段每个参数用type、required、default、enum表达约束。required数组显式列出必填参数避免模型漏传。我总结了一个可以直接抄的模板{ name: tool_name, description: 一句话说明工具功能和触发条件, parameters: { param_a: { type: string, required: true, description: 只在参数名不够直观时补充 }, param_b: { type: integer, required: false, default: 5 }, param_c: { type: string, required: false, enum: [value1, value2] } } }注意parameters里的description能省就省。现在主流模型的函数调用能力已经很强参数名本身足够表达含义只有参数名有歧义时才需要补一句。比如days就比d好source就比src好自解释的参数名能直接砍掉一整个描述字段。2.3 模型为什么反而更听得懂 schema我知道有人担心描述写短了模型是不是就不认识这个工具了实测下来恰恰相反。原因有三第一主流模型在训练阶段就吃了海量函数调用样本JSON Schema 格式是它们最熟悉的输入形态之一。你给一段自然语言散文它还要先“翻译”成内部表示你直接给 schema它几乎没有理解成本。第二schema 把判定条件显式化了。required字段直接告诉模型哪些参数必须给enum直接圈定合法取值范围模型不需要从长句里推断约束。少了推断环节就少了幻觉空间。第三上下文变干净之后注意力更集中。工具描述从 200 token 压到 35 token模型在工具块上的注意力自然聚焦到那 35 个 token 上。实测里有个很有意思的现象优化前模型偶尔会选错工具把新闻搜索请求发给天气工具优化后这类跨工具误调用明显减少因为每个工具的触发条件都被压缩成了醒目的关键词。打个比方以前每个工具是一篇带前言后记的说明文模型要扫完一整页才知道这工具干嘛现在每个工具是一张名片名字、职位、联系方式三行搞定。模型扫一眼就知道找谁办事效率自然不一样。3. 实操在 Pi Agent 里落地精简工具声明3.1 用户侧先拿这三类工具开刀不是所有工具都值得花时间优化我建议按优先级动手先处理三类收益最大的工具。第一类是低频但描述冗长的工具。有些工具可能一个月才被调用一两次但它的说明占了 300 token这个性价比极低。这类工具的description直接砍到一句话参数说明能精简就精简反正调用频率低模型偶尔理解不到位影响也不大。第二类是参数多但大部分必填的工具。把required标清楚把默认值写进default字段模型就不会每次都在要不要传参这件事上纠结。我见过一个工具声明里写了 7 个参数4 个其实有默认值作者却全标成必填模型调用时动不动就臆造参数值改完之后报错率立刻降了一半。第三类是功能重叠的工具。Pi Agent 生态里扩展很多两个扩展可能都提供“查天气”或“看日历”的能力。留着两个功能一样的工具模型每次都要在两个之间做无谓判断。我的做法是保留描述更简洁的那一个另一个在description开头加“除非主工具不可用否则不要调用本工具”的限制句既不影响功能兜底又减少模型的选择成本。操作路径很简单打开 Pi Agent 的扩展管理页找到对应扩展的“工具声明”或“配置”入口把工具定义导出来按上面说的优先级逐个重写保存后跑一两个真实任务看效果。不同版本入口位置不一样但核心都是“能覆写工具描述”这一层没有的话可以直接改扩展的本地配置清单。3.2 扩展作者侧默认工具声明的设计模板扩展作者是工具提示词膨胀的源头如果默认声明写得好用户根本不用自己动手改。我给扩展作者们一套可以直接写进默认清单的规则。description不要超过 30 个中文字符只保留两部分信息这个工具做什么、什么场景下触发。比如“按关键词检索新闻返回标题、来源和时间”就是合格的写法“新闻工具是查询系统的重要组成部分通过关键词对新闻库进行综合检索……”这种就该删掉。触发条件要前置像“仅当用户明确要求查询天气时调用”模型读到前半句就能做判断。参数名要有自解释性keyword、days、start_time这种一眼看懂的名字比k、d、t好不知道多少。能用enum约束的取值就不要留开放字符串比如新闻来源只有“官媒、财经、科技、体育”几类写成enum: [科技, 财经, 体育]模型传参准确率会高很多因为合法的选项就摆在眼前。最容易被忽略的一条不要在工具声明里写调用示例。示例是给人看的不是给模型看的。模型判断是否调用一个工具靠的是description和参数约束示例只会增加 token 开销。真遇到模型不会传参的情况正确做法是在扩展代码里加参数校验和错误提示把“教模型用工具”这件事从 prompt 转移到代码逻辑里。如果你是扩展作者还想兼顾不同用户的需求可以在 manifest 里内置两套声明一套完整版给默认配置一套轻量版给在意 token 的用户切换。我在自己的扩展里就是这个方案完整版描述控制在 80 token 以内轻量版控制在 30 token 以内用户按需选。上线之后反馈很好至少没有用户再来抱怨“你这个工具吃 token 太多”。3.3 验证效果别凭感觉跑一组对照测试改完之后别急着宣布胜利工具提示词优化是要用数据说话的。我每次调整都会跑一组固定任务集大概 15 到 20 条覆盖最高频的使用场景查询类、操作类、跨工具协作类各占三分之一。对照指标我建议记四个token 总消耗、工具命中率、调用成功率、任务完成率。工具命中率指模型是否选对了工具调用成功率指选对后参数传得对不对、有没有报错任务完成率指最终结果是否符合预期。这四个指标拆开看能定位很多问题只看一个总数容易误判。记录方式很简单Pi Agent 的请求日志里会展示每次任务用了多少 token、调了哪些工具把这些数据拉出来存个表格就行。旧配置跑一轮新配置跑一轮至少各跑两三轮取平均值避免单次请求的偶然性。我自己的实测数据供参考指标优化前优化后变化工具相关 token / 任务4520398-91.2%工具命中率92.5%96.8%4.3%调用成功率88%92%4%任务完成率90%91%1%token 开销降了 9 成多任务完成率还微涨了一点。这个结果很符合预期上下文干净了模型的有效注意力范围变大处理任务本身的质量自然提升。如果你的数据没达到这个水平先别怀疑方向优先检查是不是还有工具的声明没改到、或者某段必要的判定条件被误删了。4. 常见问题与排查技巧实录4.1 描述太短模型开始“乱点工具”最常见的翻车现场你大刀阔斧把某工具的description砍成“搜索新闻”结果模型在别的场景也开始调用它。原因是你把触发条件一并删掉了。我后来总结的规则是压缩掉的是修饰语和重复信息触发条件必须保留。一条标准的精简描述 功能 触发条件比如“按关键词检索新闻仅当用户明确要求搜索新闻时调用”。后半句看着像废话但它就是模型判断要不要出手的关键信号。如果模型还是乱点还有个排查方向两个工具的description写得太像模型分不清边界。比如“搜索新闻”和“搜索文章”在模型眼里几乎一样你需要在描述里明确区分“新闻指时效性报道”“文章指长文内容”。边界模糊的问题靠删是不够的要在关键区分点上给足信号。4.2 必填参数没标清楚调用老是报错结构化的参数声明里有两个致命细节一是required没标对二是默认值没写进default。前者会导致模型漏传必填参数运行时直接抛异常后者会导致模型每次都要猜测“这个参数不传会怎样”猜错了传个不存在的值照样报错。排查的时候逐个人工核对每个参数这个参数不传能不能跑能跑就标required: false并给默认值不能跑就标required: true。选项固定的话务必写enum我在这上面吃过亏——一个source参数没写enum模型传了“腾讯新闻”这种不在白名单里的值扩展代码校验直接拒绝用户看到的就是一次莫名其妙的失败。加上enum之后错误就再没出现过。还有一个小坑是类型。days参数声明成integer模型有时候会传字符串3。如果平台层面的校验比较宽松会自动转换校验严格的平台就会报类型错误。保险做法是在扩展代码里做个宽容转换字符串数字也能吃进去这个兜底比继续在 prompt 里强调类型省事得多。4.3 旧扩展没更新用户也能自己改很多扩展作者还在用旧格式一个工具写一大段自然语言说明。碰到这种情况不用等作者更新Pi Agent 用户可以在扩展配置里直接覆写工具声明。我之前遇到一个第三方天气扩展默认声明绕了 300 多 token我没等作者改版自己把声明覆写成 JSON schema 格式效果立刻上来了。覆写时注意一点先看一遍原始声明的参数列表别漏参数。有些作者会把参数含义藏在描述段落里而不是参数列表里你不完整看一遍就覆写容易把隐含参数弄丢。拿到完整参数清单再按第 2 节的模板重写同样能达到 90% 左右的降幅。如果平台版本较旧、不支持直接覆写退一步的办法是保留旧声明但缩短其中的示例段落。删掉两个例句通常能省 20% 到 30% 的 token虽然不如结构化声明彻底但胜在改动小、无风险。等作者发布新版再迁移也不迟。我个人现在养成的习惯是每装一个新扩展先做一次工具声明审计把明显冗余的字段和示例清掉再投入使用。别小看这一个习惯扩展越装越多每个省下来的一两百 token 在长对话里都会被反复放大。91% 这个数字不是标准答案只是一个“还能省这么多”的信号——动手看一眼自己的工具提示词你大概率也能找到一大片可以砍掉的水分。