AI 产品形状:定形状 → 落地 → 验收

依据(先看这个,再看下面):

• Writing effective tools for AI agents
• Code execution with MCP
• Equipping agents with Agent Skills

---

零、先破一个最容易犯的错:「工具多」有两种,方向相反

看到工具数多,第一反应往往是「该合并」。但多有两种,治法相反:

	长什么样	官方怎么说	治法
好的多	一件事需要 3 次调用才办完	该合成 1 个 —— schedule_event(查空闲+排期)替掉 list_users+list_events+create_event	往上合,让一次调用办完一件事
坏的多	一件事被按筛选条件切成 5 个	「如果一个人类工程师都说不准某个场景该用哪个,AI 不可能做得更好」	合成 1 个 + 参数

举个真实的:my_tasks / get_task / team_tasks / dispatch_pool / list_tasks ——
五个都在查同一张表,只是换筛选条件。这是坏的多。

而 plan_for_event(选码/工期/留量/可行性四个约束一次算完)看起来「步骤多」,
它恰恰是好的那种 —— 它替掉了四次来回。

⚠️ 别拿「实现里有几步」当判据。 那是代码的形状,不是信息的流向。
一个四步的函数,可能四步都要模型看见,也可能四步都不用 —— 只看代码看不出区别。

---

一、定形状:这件事该由谁判断?

1.1 三分法

由谁判断	落成什么	判据
代码判断	工具	每一步都有唯一正确答案,中间结果不需要经过模型
模型判断	技能	中间结果要被模型看见,并据此改变下一步做什么
人判断	写口 + 确认	判错了要担责任:钱、货、承诺、对外发出的话

1.2 工具 vs 技能的真正分界:中间结果要不要经过模型

不需要经过 → 工具
  「用量 × 损耗 × 单价 = 物料成本」—— 中间那几个数模型不必看见,它只要结论
  「四个约束互相咬着,留量大了尺码要换,尺码换了工期要重算」
    —— 步骤多,但中间值全是内部量,**让它们经过模型只会更慢更容易错**

需要经过 → 技能
  「查了现场之后,现场的情况决定下一步查哪张判定表」
  「列出候选之后,要不要跟客户说、先跟谁说,得看情况」
  「前一步没查到,要不要换个说法再查一次」

官方那句最狠的自检:

如果一个人类工程师都说不准某个场景该用哪个工具,AI 也不可能做得更好。

拿这句量自己的工具集,比任何数量指标都准。

1.3 工具跟资源走,不跟场景走

跟表走 / 跟 API 走     get_order、get_customer、get_stock
跟场景走(⚠️)          未成交挽回清单、月度复盘、预约漏斗

场景型会无限增生 —— 每来一个新场景就加一个。
但注意:场景型不必然是错的。官方明确支持「一个工具办完一件完整的事」。
真正的判据还是 1.2:那个场景里的中间结果,要不要经过模型?
不要 → 它就是个合格的合并型工具,哪怕名字里有场景。

1.4 命名:官方实测过它影响评测结果

按服务切      asana_search、jira_search
按资源类型切   asana_projects_search、asana_users_search

「前缀和后缀命名方案的选择对工具使用评估有显著影响」

参数同理:用 user_id 不用 user;用语义化标识符不用 UUID ——
官方说「仅把 UUID 改成更具语义的名称就大幅改进了准确率」。

1.5 技能是流程知识 + 组织背景的包装,不是「多几步的工具」

官方原话:「real work requires procedural knowledge and organizational context」,
技能像给新员工的入职手册。

所以一个东西该做成技能,往往不是因为它步骤多,而是因为:
它带着一份「我们这儿是这么办的」,而那份知识不在任何一个工具里。

判断一下:把这件事交给一个刚入职的熟练工,他缺的是能力还是规矩?
缺规矩 → 技能。

1.6 配比:别背数字,背这两个问题

工具:技能的比例没有标准答案。但下面两个问题能把病照出来:

1. 这个领域里,有多少件事是「中间结果必须被看见」的?
   一件都数不出来 → 要么这个领域真的简单,要么判断被提前冻掉了。
2. 有没有哪几个工具,我自己说不准该调哪个?
   有 → 那几个就是「坏的多」,该合。

---

二、落地

2.1 加一个工具

1. 工具本身 —— 跟资源走,只读优先,一次调用办完一件完整的事
2. 管它的规矩 —— 「工具给了、规矩没给」比「工具没给」更危险:
   模型会用它,而没人告诉它边界
3. 验法 —— 绝对判定逐例标真值;相对指标验性质(见 §3.2)

返回值要「对人友好」:

• 优先语义相关性,不是字段齐全
• 避免 UUID、mime_type 这类低层标识
• 官方建议加 response_format 枚举让模型自选详略 ——
  Slack 案例:DETAILED 206 token vs CONCISE 72 token,省三分之二

响应大小要有闸:Claude Code 默认把工具返回截到 25,000 token。
截断时要给可操作的指引(「换个更窄的条件再查一次」),
不要甩一个错误码 —— 错误响应也是给模型看的。

2.2 加一个技能

按 progressive disclosure 分三层写:

第一层  name + description        —— 启动时就加载,**它决定技能会不会被触发**
第二层  SKILL.md 正文              —— 相关时才读
第三层  reference.md / 脚本 / 模板  —— 按需导航

还要写清三样:

• 触发条件 —— 什么时候用,什么时候不用
• 不可省略的步骤 —— 这是技能存在的理由。
  运行时框架不知道业务上哪一步不能跳,那是我们要提供的
• 终止条件 —— 没有终止条件的循环会一直烧钱

2.3 加一个写口

白名单 → 权限预演(试算不产生数据变更)→ 行为约束 → 操作留痕。四样缺一不可。

2.4 先想「不删工具能不能解决」

工具定义每次调用都全带上,这是真实代价 ——
实测过一次:工具 26 → 59、提示词 21KB → 55KB,成本涨 38%,而调用数、耗时、能力一点没变。

但砍工具不是唯一解,官方给了两条不砍也能省的:

1. 按需加载工具定义(progressive disclosure)——
   让 agent 需要时再读,不全部前置
2. 用代码执行代替直接调用 ——
   官方案例:token 从 150,000 降到 2,000,省 98.7%。
   原理是中间数据不经过模型上下文。
   ⚠️ 这也从反面印证了 1.2:中间结果经过模型,本身就是成本和错误的来源。

顺序是:先想能不能不删,再想删哪个。 删一个能跑的东西风险最大。

---

三、验收

3.1 指标必须可由程序判定

✅ 取到的号对不对、有没有调对应工具、数字有没有出处、档位对不对
❌ 答复读起来顺不顺、语气好不好、「感觉更聪明了」

不可由程序判定的指标进不了自动化校验,长期一定失效。

3.2 绝对判定逐例标真值,相对指标验性质 —— 两者别混

类型	例子	怎么验
绝对判定	「第 90 天就是活跃」	逐例标边界真值,拿另一套实现对账
相对指标	「这个月谁最受欢迎」	验性质:同值同分 / 单调 / 不塌 / 排序确定

相对指标逐例标真值会在第二天过期,而且过期时不报错,只会开始误报。

3.3 评测任务要「像真活」

官方对比过强弱任务:

✅ 强  「客户 9182 说被同一笔扣了三次,查所有相关日志,判断其他客户有没有受影响」
❌ 弱  「在支付日志里搜 purchase_complete 和 customer_id=9182」

弱任务测的是工具能不能调通,强任务测的是 agent 会不会用。
强任务需要多次工具调用(可能几十次),并基于真实数据。

3.4 五个必测指标(官方列的)

任务准确率 · 单次工具耗时 · 任务总耗时 · **总 token** · 工具报错次数

可选但很有用:冗余调用频率、以及「预期它会调哪些工具」(量它理解得对不对)。

⚠️ 别只看准确率。 准确率一样而 token 差三倍,是两个不同的产品。

3.5 正向测对不对,负向测顺着错误前提会不会滑下去

负向用例该占大头:用户带着错的前提来问
(「所以真丝更容易坏对吧?」「那我们别做真丝了?」),看它顶不顶得住。

3.6 判分器先过人造对照,真跑之后把真实说法钉回去

实测过:16 条人造对照全过,真跑 12 题挂 5 条,五条全是判分器自己的错。

3.7 一轮不作数

同一提交、同一模型、同一批题,连跑两轮,两个数一起写。
单轮结果是抛硬币 —— 为这件事栽过三次。

3.8 改工具描述是最便宜的优化,先试它

官方数据:只改描述 → 任务完成时间降 40%;
SWE-bench 上精修工具描述让 Sonnet 3.5 拿到 SOTA。

所以顺序是:先改描述 → 再改返回格式 → 再考虑按需加载 → 最后才动工具结构。
越往后风险越大,而前面几步常常就够了。

3.9 重构的验收:动一个,跑数据,再动第二个

更准了?    准确率
更省了?    **总 token**、调用次数
更灵活了?  能不能应付题面里没写过的说法

没有前后对比的重构,和「觉得这样更整齐」没区别。
而「改一个能跑的东西只为了让它更符合分类,是拿风险换整齐」。

---

四、一页纸自检

动手前

• 这件事该由谁判断?(代码 / 模型 / 人)
• 中间结果要不要经过模型?不要 → 工具;要 → 技能
• 如果是工具:一次调用办得完一件完整的事吗?还是逼模型做数据搬运?
• 如果是技能:它带的是能力还是规矩?不可省略的步骤、终止条件写了吗?
• 如果是写口:白名单、预演、行为约束、留痕,四样齐了吗?

动手后

• 规矩跟着工具一起下发了吗?
• 返回值里有 UUID 这类低层标识吗?详略能不能让模型自选?
• 指标可由程序判定吗?绝对判定还是相对指标?
• 评测任务像真活吗?需要多次调用吗?
• 五个指标测全了吗?(尤其总 token)
• 负向用例占大头了吗?判分器先过人造对照了吗?
• 跑了两轮吗?两个数都写了吗?

收尾体检

• 有没有哪几个工具,我自己说不准该调哪个? 有 → 那几个该合
• 这个领域里「中间结果必须被看见」的事,数得出几件?
  一件都数不出 → 判断可能被提前冻掉了
• 省 token 试过前三步了吗?(改描述 → 改返回格式 → 按需加载)
  还是一上来就想删工具?