L03-03 工具设计：工具多了模型就选不准

全局中心内容：工具描述的质量决定调用准确率，description 比代码更重要。 全局讲解主线：选错工具的翻车 → 描述三要素 → 参数设计 → 数量控制 → 风险分级 → 编码 → 验证。

---

P1 · 产出页

中心内容：一套带风险分级、可动态挂载的工具注册表。

• 讲解技巧
  • 开场场景：注册了 30 个工具后，模型开始乱调——这是非常普遍的真实问题。
  • 结论：工具不是越多越好，是越准越好。
• 时长：20s

---

P2 · 描述三要素

中心内容：做什么 / 什么时候用 / 什么时候不要用。

• 页面内容：坏描述 vs 好描述对照

• 讲解技巧

  • 这页是全节重点：举例「查订单」的坏描述只有「查询订单」，好描述会写「按订单号查询单个订单详情；批量查询请用 searchOrders」。
  • 强调第三要素最有效：明确写出「不要用它的场景」，能显著减少误调。

• 时长：6min

---

P3 · 参数设计

中心内容：参数要少、要枚举、要有 @ToolParam 说明。

• 页面内容：参数设计正反例

• 讲解技巧

  • 讲清原则：能用枚举就不要让模型自由发挥，能用两个简单参数就不要用一个复杂对象。
  • 提醒必填/选填要标清楚，模型经常漏传可选参数。

• 时长：5min

---

P4 · 数量控制

中心内容：同时挂载的工具控制在 8 个以内。

• 页面内容：工具数量与调用准确率的关系曲线

• 讲解技巧

  • 给经验数字：超过 8 个后准确率明显下滑，超过 20 个基本失控。
  • 提示这是后面动态挂载（本页后半）的动机。

• 时长：4min

---

P5 · 动态挂载

中心内容：按任务阶段只挂载当前可能用到的工具。

• 页面内容：三级选择（阶段 → 关键词 → 语义匹配）

• 讲解技巧

  • 讲三级策略的价值：规则先行（便宜可靠），语义兜底（覆盖长尾）。
  • 提醒要有「兜底全集」，否则语义匹配失败时 Agent 无工具可用。

• 时长：5min

---

P6 · 风险分级

中心内容：READ_ONLY / WRITE / DESTRUCTIVE / NEED_APPROVAL 四级。

• 页面内容：ToolMeta 设计与每级的处理策略

• 讲解技巧

  • 强调这是后面所有防护的基础：权限、审批、重试策略都要读这个字段。
  • 提醒分级要保守：拿不准就往高定，误判成只读的代价是事故。

• 时长：5min

---

P7 · 错误返回值

中心内容：工具抛异常要说人话，别把堆栈喂给模型。

• 页面内容：异常转人类可读文本的写法

• 讲解技巧

  • 讲清为什么重要：模型看到堆栈只会更困惑，看到「订单号不存在，请检查格式」则能自我纠正。
  • 提醒不要吞掉错误，错误信息要能指导下一步行动。

• 时长：4min

---

P8 · 编码：注册表

中心内容：ToolRegistry 管理元数据与挂载。

• 页面内容：注册表实现与按阶段过滤

• 讲解技巧

  • 强调元数据和实现绑定在一起，避免两处维护不一致。

• 时长：5min

---

P9 · 避坑与小结

中心内容：改工具描述要重新评测，它和改代码一样有风险。

• 讲解技巧
  • 引出下一节：一个 Agent 不够用怎么办——03-04 多 Agent 协作。
• 时长：2min

---

讲师备忘

项	内容
课前必做	准备坏/好描述对照；准备 30 工具选错的日志
最容易超时处	P2 描述部分，容易被要求现场改写——控制在 6 分钟
学员最常问	「描述可以写多长？」答：3~5 句，够说清边界即可，太长会稀释注意力
现场备用	无网络 → 用预生成的调用结果讲解