Agent Skill 工具调用成功率评估方法（详解工具选错、参数非法、重复调用与高风险误调用四大指标）

衡量一个 Agent Skill 是否真正”让工具调用变好”，不能只盯最终任务成功率，必须把失败拆到”工具选错、参数非法、无意义重复、高风险误调用”四条独立维度上分别计数。任何一项失守，都可能让”看上去能用”的 Skill 在生产里悄悄烧 token、污染数据，甚至触发不可逆操作。下面给出每个维度的可计算指标、可落地的采集方式，以及把它们组合成发布门禁的步骤。

一、为什么不能只看”任务成功率”

任务成功率是聚合指标，掩盖了”哪一步在出错”。一个 70% 通过率的 Skill，可能是 30% 的任务整段没调对工具，也可能是每个任务都调了 3 次才对、token 翻倍。把失败拆到原子动作才能定位”是描述写得不好”还是”参数 schema 写得不好”。

二、四大失败维度与可计算指标

下面这张表是给一个 Skill 上线评估时的最小指标集，四个维度相互正交、可独立告警。

2.1 工具选错率

工具选错率 = 模型挑了与 gold label 不一致的工具 / 总调用次数。常见错配有三类：把 Read 错用成 Glob（已知路径还去通配）、把 Edit 错用成 Write（局部改动却整文件覆盖）、把 Grep 错用成 Bash（用 shell 而非专用工具）。评估时按”工具名”做精确匹配计数即可，不要用语义模糊度去打分；schema 层面过不了再算参数非法。

2.2 参数非法率

参数非法率 = JSON Schema 校验失败次数 / 总调用次数。统计时把”必填字段缺失””枚举值越界””类型不匹配”统一计入”非法”；语义正确但参数”过于宽泛”（例如 Edit 里 old_string 一次性匹配了十处）单独算”语义过宽”，不放进非法率。两者都修，但修法不同：非法改 schema，过宽改 SKILL.md 里的示例与”最小变更”提示。

2.3 无意义重复调用率

无意义重复调用率 = 同一目标连续 2 次以上相同参数调用 / 总会话数。判断”无意义”用三条规则：相同工具名、相同参数哈希、且上次返回结果未被消费。满足这三条才记一次。重复调用常常不是 Skill 写得差，而是模型没意识到上一次结果已经够了，需要在 SKILL.md 里明确”读取工具输出后再决定下一步”。

2.4 高风险误调用率

高风险误调用率 = 在不该触发的会话里触发了不可逆工具 / 总会话数。不可逆工具指 Write、Bash(rm / curl 外发 / 数据库删除类) 等；它的分子与前三个维度独立计数，因为前三个是”做对做错”，高风险误调用是”该不该做”。

三、配套的两条质量基线

仅有四个失败维度还不足以判断 Skill 整体好坏，需要再叠加两条质量基线做交叉验证：

方差是最容易被忽略的指标。平均通过率 85% 但单次结果在 60% 到 100% 之间漂移的 Skill，比平均 80% 但稳定的 Skill 更难在生产里使用——每次跑都可能踩到不同分支。

四、采集与发布门禁

把上面六个指标组合进发布门禁，落地步骤如下：

1. 准备 30~50 条贴近真实用法的 prompt，正负样本各半，硬负样本要”看起来很像但不该触发”；
2. 用同一个模型版本对每条 prompt 跑 N 次（推荐 3 次起步），把工具名、参数、结果都记成 JSON 流；
3. 对每条调用跑一次 schema 校验（确定性、毫秒级），对 Edit / Write / Bash 再加一次语义 rubric（LLM-as-Judge）；
4. 算出四个失败率 + 两条质量基线，与”硬门槛”对比；任意一项越线就回退到描述 / schema 改写；
5. 把本次基线数值落到版本号上，未来模型升级或 Skill 改动都跑同一组 prompt，看 delta 而非绝对值。

4.1 硬门槛的设定思路

不要凭空拍一个”90% 必须通过”。先跑 5~10 轮 baseline 得到对照，再给”高风险误调用率”加零容忍门禁（任何非零都失败），给”重复调用率”加宽松门禁（个位数百分比可接受），给”工具选错率”按”是否引入新工具类别”分档。

4.2 评估成本与采样

每条 prompt 跑 3 次意味着 100 条 prompt 就有 300 次完整工具调用，按一般 token 单价算不便宜。建议把”必跑集”控制在 30~50 条作为门禁，把”抽样集”放 200 条以上做月度回顾，避免每改一次 SKILL.md 都跑全量。

五、一段可直接复用的评估脚本骨架

下面这段伪代码把”采集 + 算分 + 落库”三件事拼在一起，便于嵌进 CI：

from jsonschema import validate, ValidationError
from collections import defaultdict

def evaluate(trace, gold_label, schema_registry):
    # trace: list of {tool, args, result} for one session
    stats = defaultdict(int)
    stats["total"] = len(trace)
    prev = None
    for call in trace:
        # 1. 工具选错率
        if call["tool"] != gold_label[call["step"]]["tool"]:
            stats["wrong_tool"] += 1
        # 2. 参数非法率
        try:
            validate(call["args"], schema_registry[call["tool"]])
        except ValidationError:
            stats["invalid_args"] += 1
        # 3. 无意义重复
        if prev and prev["tool"] == call["tool"] and prev["args"] == call["args"]:
            stats["no_progress_repeat"] += 1
        prev = call
    # 4. 高风险误调用率
    stats["risky_misfire"] = sum(
        1 for c in trace if c["tool"] in {"Write", "Bash"}
        and not c.get("confirmed_by_human", False)
    )
    return stats

效果上，这段骨架能在一秒内对几百条调用跑完 schema 校验与重复检测；高风险误调用那条建议接在人工复核之后，避免漏判。注意点是”gold label 必须来自人工标注”，不要让被测 Skill 自己当裁判，否则会形成自证循环。

六、四个维度的优先级与修复顺序

四个维度不是平级的，修复时要分清先后：

先 P0 后 P3 的好处是：安全防线先就位，再去抠效率。

到这里，”四个失败维度 + 两条质量基线 + 采集脚本 + 修复优先级”就构成了一套可重复运行的评估闭环。每改一次 SKILL.md 跑一遍同一批 prompt，看 delta 决定是否合并。

常见问题（FAQ）

Q1：任务成功率与四个失败率冲突时以谁为准？

以四个失败率中”高风险误调用率”为准。任务通过但高风险工具被误触发的 Skill 不能上线。

Q2：基线怎么定？

先跑 5~10 轮无 Skill 的 baseline，把每次”同一 prompt + 无 Skill”的指标记录下来，所有后续评估都和这套基线对比 delta。

Q3：评估要走多少次才算稳？

每个 prompt 至少 3 次重复，标准差控制在均值 10% 以内可视为稳定；超过则把每 prompt 重复次数加到 5。