工具设计工程学：写给模型看的 API 文档
2026/8/23大约 2 分钟
AICon 2026 学习系列 · 阶段 3 · Agent 工程 · 第 17/43 篇 · 🚧 占位待学
上一篇：《ReAct 循环：思考-行动-观察》
下一篇：《MCP：工具生态的 USB-C》
学习大纲：《AICon 2026 学习总纲》
状态：待学习。 本文为占位文档：知识点清单、实验与验收标准已就绪，正文待按「先学习、先实验、再撰写」补全。
对应总纲单元：阶段 3 · 单元 3.2
一、本文要解决的问题
同一个 Agent，换一套工具描述，成功率判若两 Agent。工具文档是写给模型看的 API 文档——命名、描述、参数、错误信息，每一项都是提示工程。
二、知识点清单
- 工具三要素的写法：name 要自解释、description 要说清何时用 / 何时不用、参数 schema 要带示例
- 工具粒度设计：一个粗工具 vs 多个细工具的取舍
- 错误返回的设计：错误信息是给模型的下一步提示
- 工具数量与选择精度：工具多了选不准的困境
三、动手实验（学习时必须真跑）
- 同一任务给 Agent 换三套工具描述（模糊 / 清晰 / 带反例与错误说明），各跑 20 次统计成功率
- 故意返回模糊错误（failed），观察 Agent 反复撞墙；改成明确错误后对比
四、验收标准（全部通过才进入下一篇）
五、写作提示（补正文时遵守）
- 开篇问题驱动；结构走「是什么 → 为什么 → 怎么做 → 背景知识」
- 所有代码、命令、输出必须先在本机跑通再写入，不得杜撰
- 版本口径以总纲环境清单为准（Python 3.12 / Ollama / vLLM 与 SGLang 最新版 / Spring AI 1.x）
- 涉及版本敏感结论时标注出处与时间
本篇完成后，把文首导航块的「🚧 占位待学」去掉，并在总纲处打卡。