SuperAPI AI 工具集

audit-mcp-tool-friction

智能体与模型

查看项目

更新于 10-27 06:47

技能介绍

该技能用于审计智能体在选定某个 MCP 工具后,是否能够形成有效请求、从失败中恢复,并正确使用返回结果。它的定位是公开契约审计,不以调用次数为目标,也不测试模型是否愿意使用某个工具。

使用前需要界定审计范围,记录工具、修订版本、客户端、任务或追踪记录,以及所检查的公开输入,并把三类问题分开:采用问题(智能体是否看到、发现或选择了工具)、摩擦问题(已选中的工具是否把契约、有效输入、错误恢复和结果使用说明得足够清楚,以便正确执行)、能力问题(某项操作是否真正覆盖所需工作)。资料明确指出,不能因为 Python 回退成功就认定工具契约易用,也不能在未核查公开契约事先暴露内容的情况下,把单次畸形请求当作产品缺陷。

检查公开契约时,应针对每个相关操作查看生成的 MCP 输入与输出模式、工具描述、发现或检查结果、操作示例和错误消息,并把每项非显而易见的必需条件追溯到其归属方,包括:输入表达(所需值、单位、编码、顺序和边界是否在调用前可见)、模式投影(JSON Schema 可表达的约束是否出现,并配有有用的字段说明和示例)、语义验证(仅由模型验证器执行的规则是否有明确描述和最小有效示例)、恢复(错误是否指出字段并给出最小具体修正)、结果使用(结果形状、精确性、限制和重建信息是否足以让调用方继续而无需猜测)。资料提醒,Pydantic 不会从自定义模型验证器推断 JSON Schema 描述或示例;当语义不变量无法编码为标准 JSON Schema 约束时,应添加 Field(description=..., examples=...) 或适当的 json_schema_extra。

读取追踪记录时,应把它当作恢复过程:捕获确切的操作 ID、首次载荷、带类型的结果或错误、重试以及值的最终使用,并狭窄地归类首次失败,例如隐藏的表示规则、示例或描述不足、无帮助的恢复、工具或传输缺陷、智能体失误。应把一次直接已知有效的执行与追踪记录分开比较:直接通过证明操作可用,但不能消除调用方摩擦;没有调用的追踪记录不在范围内,除非正在审查可用性或采用情况。

衡量基准摩擦时,对于可比较的运行,需冻结任务、镜像、服务器修订、模型、客户端、预算和 MCP 配置,并把最终验证器结果与首次调用有效性、执行前的操作检查、按字段和不变量分类的验证失败、恢复尝试及重试是否使用返回错误、带类型结果使用与手动回退的对比、以及新增调用、令牌和耗时分别报告。应在多次重复任务或尝试后再声称稳定比率。

修复建议按顺序优先:更清晰的字段元数据和示例、可操作的错误、模式级约束、范围狭窄的适配器或助手。只有在保留文档化数学含义、不隐藏歧义、重复项或调用方错误时才规范化输入,并保留有界操作语义和直接返回值。报告应包含已确认行为、确切公开证据、受影响阶段、相称修复以及仍未测试的内容;当证据只支持智能体失误而非工具设计发现时,应明确说明。