给 Agent 用的工具接口：找得到、调得对、错了知道怎么办

同一个工具，人用的时候可以翻文档、凭经验排错；交给 Agent 用，这些信息就得明明白白写进接口里。我最在意三件事：它能不能找到合适的工具，能不能把参数填对，出错之后知不知道下一步干嘛。

MCP 管交换，设计还得靠自己

MCP（模型上下文协议）让兼容的 AI 应用用同一套接口访问各种服务。不过接上之后好不好用，还要看客户端支持到什么程度、权限怎么给、部署在哪。

按 MCP 的服务端概念文档，三种能力的区别在于谁来控制：

类型	干什么	谁说了算
Tools	模型可以主动调用的功能，比如查数据、改数据	模型
Resources	应用读出来塞进上下文的资料	应用
Prompts	用户挑着用的预设模板	用户

工具用 tools/list 列出来，用 tools/call 调用。MCP 的架构文档也讲得很清楚：协议只管交换，模型怎么用、上下文怎么组织是宿主应用的事。

我会先看的六件事

1. 描述要能帮它挑。 写清楚能干什么、什么时候用、有什么限制、返回什么样子。别让几个工具的描述看起来差不多。

2. 分工清楚，数量合理。 相近的工具可以合并，但不是越少越好。合到参数一大堆、权限混在一起，反而更难用。

3. 参数约束要能执行。 类型、必填、取值范围写进 schema，服务端再检查业务规则。能用接口卡住的，就别只写在提示词里。

4. 报错要告诉它下一步。 参数错了，说清是哪个字段、允许什么；权限不够，说清缺什么；临时故障，说清能不能重试。结构化的错误码加一句短说明，人和模型都好判断。

5. 有副作用的要说清楚。 改数据、发消息这种操作，要让调用方知道后果，并由宿主或服务端真的去做授权。接口描述里写一句「请先确认」可不算权限控制。

6. Tool 还是 Resource，看谁控制。 只读不等于就该做成 Resource。应用主动提供的文档适合做 Resource；模型根据问题自己发起的搜索和查询，就算只读，也可以是 Tool。

核心只写一份

命令行和 Agent 接口最好共用同一套核心逻辑，区别只放在参数适配和结果展示那一层。不然同一个功能写两遍，边界、错误处理、默认值迟早对不上。

测接口也别只测一次调用成功，要专门测失败：参数错了它能不能改对，权限不够会不会误执行，临时故障会不会让它一直傻重试。

这六条是我自己的取舍。协议统一了怎么交换，至于工具能干什么、出错怎么恢复、谁有权执行，还得自己去设计。