智能体工具设计实践：工具数量、命名空间与返回的六条原则

智能体的工具设计，最容易犯的错是工具太多、边界重叠。 Anthropic 在《 Writing effective tools for agents 》里给出的判断标准非常实用：如果人类工程师都说不清某个场景该用哪个工具，就别指望模型能选对。好的工具集应该是自包含、抗误用、职责不重叠的最小集合。

先分清：工具不是给开发者写的 API

传统函数的调用方是确定性系统，getWeather("NYC") 永远按同样方式执行。工具的调用方是模型：同一个问题它可能调工具、可能直接答、也可能先反问。所以设计目标不是”接口完备”，而是扩大模型能有效完成任务的概率面积。

一个直观的类比：解一道难题，纸笔是最低配，计算器更好，能写代码的计算机最强——但你得先知道它会用什么。给智能体配工具同理，要按它自身的能力形状来配，而不是按你的模块划分来配。

六条设计原则

1. 少而准，别贪多：能不实现的工具就不实现。工具集膨胀会带来两个后果——占用上下文、制造选择歧义。定期删比定期加更重要。
2. 用命名空间划定边界：按资源或动作前缀分组（如 search_*、user_*），让功能边界一眼可见，减少误选。
3. 返回有意义的上下文，而不只是原始数据：返回”找到了 3 条，其中 1 条已过期”比丢 300 行 JSON 有用得多。
4. 为 token 效率优化返回：支持分页、字段选择和摘要模式，别让一次调用吃掉半个上下文窗口。
5. 把工具描述当提示词来写：包含用途、示例、边界条件、输入格式要求，以及与相邻工具的区别——就像写给团队新人的 docstring 。
6. 防呆设计（poka-yoke）：改参数让错误更难发生。经典案例是强制使用绝对路径，模型在切换工作目录后就不再写错相对路径。

工具数量到底多少合适

更有效的替代思路是给一个通用执行能力（如 bash 或代码执行），再配少量专用工具。模型越强，越能用通用工具自己解决长尾问题——这也是很多团队最终收敛到的形态。

一个失败到成功的真实迭代

Anthropic 在设计”向用户提问”这个能力时走了三步：先试着给已有的 ExitPlanTool 加一个 questions 参数，结果模型困惑——同时要计划和关于计划的问题，冲突了怎么办？再试着改输出格式，让模型用特定 markdown 输出问题，模型能写出来但不稳定，会加多余句子、丢选项。最后才落地为一个独立的 AskUserQuestion 工具：模型可随时调用，触发时弹窗并阻塞循环直到用户回答。结论是——工具要顺着模型的行为习惯设计，而不是顺着现有代码结构塞参数。

怎么验证工具好不好用

1. 先做原型并亲手试用：自己跑一遍找毛刺，比看日志快。
2. 造评测任务集：任务要来自真实场景、基于真实数据，好的任务通常需要多次（甚至几十次）工具调用。
3. 跑评测、看失败模式：重点看”该调没调””调错了工具””参数写错”三类。
4. 让智能体参与改进：把评测与失败样本交给它，让它改描述和参数，再用留出测试集验证，避免过拟合。

工具描述写多长、示例放几个，本质上是上下文工程的问题：用最小的高信号 token 让模型一次做对。工具调用本身的实现细节，可以参考OpenAI Function Calling 实战；如果任务本身步骤多，还该配合Planning 规划模式先出计划再调工具。