本页目录
L04 — 多工具与工具设计
本课目标：学会设计好用的工具，理解"工具越多越难选"的权衡。前 3 课你只用了 2-3 个工具，这课配 5+ 个工具，看模型怎么选、为什么会选错、怎么设计工具才能避免选错。
工具设计是 Agent 工程师的核心技能——同样的模型，工具设计得好坏，效果天差地别。
1. 好工具的四个特征
设计一个"好用"的工具（模型容易选对、用对的工具），有四个特征：
① description 清晰具体
description 是模型的"选工具依据"。模糊的 description = 模型乱选。
| 差的 description | 好的 description |
|---|---|
| "处理字符串" | "计算字符串的字符数。当用户问'XX有几个字''XX多长'时使用" |
| "数学工具" | "计算数学表达式。需要精确计算加减乘除时使用。expression 如 '12*34'" |
| "查询功能" | "查询指定城市的天气。当用户问'XX天气''下雨吗'时使用" |
好 description 包含：做什么 + 什么时候用 + 关键参数说明。
② 参数简单
参数越少、越简单，模型传对参数的概率越高。
| 复杂（容易传错） | 简单（容易传对） |
|---|---|
| 10 个参数，含嵌套对象 | 1-3 个参数，都是基础类型 |
| 需要传完整 JSON 结构 | 只传一个字符串 |
参数名是缩写 cnt、ts |
参数名是完整单词 city、timestamp |
③ 单一职责
一个工具只做一件事。不要设计"又能查天气又能算数"的万能工具。
| 违反单一职责 | 遵守单一职责 |
|---|---|
do_anything(task, params) —— 啥都能干 |
get_weather + calculator 分开 |
| 模型不知道什么时候该调它 | 模型清晰知道每个工具的用途 |
④ 返回结构化、信息充分
工具的返回值要包含模型需要的所有信息，方便它下一步决策。
| 差的返回 | 好的返回 |
|---|---|
"25" （只有数字，模型不知道单位） |
"北京：晴，25°C"（城市+天气+温度+单位） |
"error" （不知道什么错） |
"错误：城市'火星'不在支持列表中，支持：北京、上海..." |
🎯 核心认知：工具返回的信息质量，直接影响模型下一步的决策质量。返回得越清楚，模型越少犯错。
2. "工具越多越好吗？"——选择的难题
直觉上，给 Agent 配的工具越多，它越强大。但实际上，工具越多，模型选错的概率越高。
原因： - 模型靠 description 做模式匹配选工具 - 工具一多，description 之间容易"语义重叠"，模型分不清该选哪个 - 研究表明，工具数量超过 ~10-15 个时，选择准确率明显下降
两个常见的"选错"场景
场景 A：功能重叠，选了相近但不对的工具
工具：sum_numbers（求和） vs calculator（通用计算）
用户问："1+2+3+4 等于多少？"
模型可能选 calculator，也可能选 sum_numbers —— 如果两个都"看起来对"，就靠运气
场景 B：description 模糊，选了完全无关的工具
工具：format_text（格式化文本，description 写得很模糊："处理文本"）
用户问："北京天气？"
模型可能误选 format_text —— 因为 description 太泛了
怎么应对？
| 策略 | 做法 |
|---|---|
| 控制数量 | 不用的工具别注册；按场景动态加载工具子集 |
| description 区分度高 | 让每个工具的 description 互不重叠 |
| 合并重叠工具 | 如果两个工具功能相近，合并成一个 |
| 工具路由 | 先用一个轻量模型判断"该用哪类工具"，再加载那类工具 |
3. description 怎么写模型才选得对
description 是 function calling 的灵魂。几个写法技巧：
技巧 1：写明"什么时候用"
差：查询天气
好：查询指定城市的实时天气。当用户问"XX天气""XX下雨吗""气温多少"时使用。
技巧 2：写明"不适用什么"（防误选）
"计算数学表达式。注意：本工具只做四则运算，不能解方程、不能求导。"
明确边界能减少模型误选。
技巧 3：给参数举例子
"expression 是数学表达式字符串，例如 '12 * 34' 或 '(1+2)*3'"
例子比抽象描述更能帮模型正确传参。
技巧 4：用用户会用的词
用户说"算一下"，description 里就写"需要计算时使用"，而不是写"执行算术运算"——这样语义匹配度更高。
💡 一个反直觉的点：description 不是写给开发者看的文档，而是写给模型的"广告语"。要站在"模型会怎么匹配用户问题"的角度来写。
4. 本课代码会做什么
code.py 配 6 个工具，做三个实验观察工具选择的难点：
① 6 个工具的"工具箱"
get_weather（天气）calculator（计算）string_length（字符串长度）string_reverse（字符串反转）list_sort（列表排序）unit_convert（单位换算：米/千米、摄氏/华氏等）
② 实验：复杂任务的多工具配合
一个需要 3+ 工具配合的任务，观察 Agent 怎么按顺序选工具、工具之间的衔接。
③ 实验：description 模糊会导致选错
故意用一个 description 模糊的工具，看 Agent 会不会误选。对比好的 description，体会差异。
④ 实验：功能重叠工具的困扰
配两个功能重叠的工具（如 sum_numbers 和 calculator），看 Agent 怎么纠结。
5. 跑起来
python agent-lessons/04_tool_design/code.py
终端会打印 Agent 在不同工具配置下的选择过程。重点观察：description 好的时候 Agent 选得准，模糊的时候会选错。
下一课 L05 — 记忆 会讲：Agent 怎么记住前面说过的话（多轮对话）。