阶段 5 实践 — 15 个 MCP 工具的粒度重审

阶段 5 实践 — 15 个 MCP 工具的粒度重审

本实践的产出 ⭐ 最小产出：国际机票 Agent 15 个 MCP 工具的粒度与命名重审报告 完整产出：重审报告 + 只读/副作用工具契约各一份 + 三类错误返回设计 + 最小 Skill

预计投入：6～8 小时。这份报告是可以直接拿出去展示的作品——它体现的正是 Agent 产品经理区别于传统产品经理的核心能力。

实践 1 · 工具面重审报告（⭐ 必做）

第一步：把现状摊开

对国际机票 Agent 现有的每个 MCP 工具，填一行：

数据来源：真实调用几次统计返回 token，不要估。

第二步：命名体检

对每个工具名逐条打分（0/1）：

• 是动词+宾语结构
• 从名字能推出它属于哪个业务域
• 与其他工具没有语义重叠（不存在两个工具都能"查价格"）
• 名字里不含内部术语（内部系统代号、表名、接口编号）

命名重叠是选错工具的头号原因。任何两个工具的职责边界，都要能用一句话说清"什么时候用这个不用那个"。

第三步：描述体检

每个工具的描述必须包含四段，缺哪段标哪段：

第四步：粒度判定与改造建议

对每个工具用讲义第二节的判据判定：

看这一步失败时，模型能不能自己修。

给出四类结论之一：保留 / 合并 / 拆分 / 下线，每条附一句理由。

第五步：返回值瘦身

对返回 token 排前 3 的工具，各做一次瘦身设计：

验收标准：

• 15 个工具全部有粒度判定与结论
• 至少识别出 2 处命名或职责重叠
• 至少 1 个"合并"和 1 个"拆分"的建议，且理由是基于失败可修性而不是"看起来更整齐"
• 返回值瘦身有 token 数字支撑

存放：ai-output/temporary/drafts/ 起草，定稿后可进 产品文档/ 或本目录。

实践 2 · 两份完整工具契约

写两份可以直接交付研发的工具契约：一个只读、一个有副作用。

A · 只读工具（推荐 get_published_fare）

必须写全：

name
description       做什么 / 何时用 / 何时不用
parameters        每个参数: 类型 / 必填 / 格式 / 枚举 / 示例 / 默认值
returns           字段清单 + 每个字段的业务含义 + 分页约定
errors            分类错误码表
side_effects      none
rate_limit        调用频率约束
data_freshness    数据时效（这条常被漏掉，但对运价类工具至关重要）

B · 有副作用工具（推荐 hold_seat 或 create_order）

在 A 的基础上追加：

side_effects      可撤销 / 不可撤销，具体改变了什么
idempotency_key   构成方式 + 有效期
confirmation      是否需要用户确认 / 确认时要展示哪些信息
timeout_semantics 超时后状态未知时的查询方式
rollback          能否撤销 / 怎么撤销 / 撤销的时间窗
audit             这次调用要记录哪些字段

confirmation 里要展示什么，是产品定义 占座确认框上应该出现：航班号、日期、乘客数、占座有效期、是否产生费用。少写一项，用户就会在事后说"我不知道会这样"。这一条在阶段 11、12 会继续展开，但它的源头在工具契约里。

验收：把两份契约给研发看，对方不需要追问就能实现。

实践 3 · 三类错误返回设计

为同一个工具设计三类错误，并在阶段 4 的最小 Loop 上实测模型的反应：

记录：每类各跑 5 次，统计模型是否给出预期反应。

要看到的现象：

• 权限错误如果写得像普通失败，模型会反复重试——这是烧钱最快的模式
• 业务失败如果不明确区分"无结果"与"查询失败"，模型可能编造结果

产出：一张《错误码 → 模型应有反应》对照表，作为工具契约的附录。

实践 4 · 创建一个最小 Skill 并验证触发

任务：为一个真实的重复性工作做一个 Skill。候选（挑一个真的会用到的）：

• 国际机票退改规则的标准解读流程
• 一份 PRD 的自查清单
• 运价异常的排查步骤

要求：

• 遵循三级渐进式披露：frontmatter 只写触发信息，正文写流程，细节放附件
• description 里写清触发词与场景
• 正文 ≤ 200 行，超了就拆附件

触发验证（这一步是重点，很多人只做正向测试）：

验收：

• 3 个正向用例至少中 2 个
• 2 个反向用例都不触发——误触发比不触发更有害，因为它会用错误的流程覆盖正确的判断
• 如果反向用例误触发，修 description 而不是修正文

参考本仓 .claude/skills/ 下任意技能的写法，以及 .claude/references/skill-development-standards.md。

实践 5（可选）· MCP 新规范的影响评估

如果国际机票 Agent 的工具面通过 MCP 暴露，做一次影响评估：

评估前先看规范原文 见 MCP 官方博客 与规范页。二手报道对部分特性弃用状态的说法不一致，涉及改造排期的结论必须以官方文本为准。

自测

通过标志 能对着工具清单说出"哪一个工具的存在，让这个 Agent 能做别人做不了的事"。如果答不上来，说明工具面还只是内部 API 的镜像，产品价值没有沉淀在这一层。

Related Documents

• 阶段 5 讲义
• 阶段 4 实践：最小 Agent Loop
• 阶段 11 实践：授权矩阵
• 学习路线