让智能体选对工具，先补好接口描述

dev.to 的一篇文章把智能体选工具的问题，落到了接口描述上：接口能调用，还得让智能体知道何时该选它。文章引用一项尚未经过同行评审的预印本，称在功能相同的服务器对比中，智能体有 72% 的时候选择了描述符合规范的一方。这个比例有实验边界，不能直接当成业务接口的选中率。

目前能确认什么

文章区分了三个层次：文档发现、接口调用契约和工具选择。

llms.txt 提供文档入口；OpenAPI 描述参数、鉴权和响应等调用约定；工具描述则帮助智能体判断当前任务适合哪个操作。三者解决的问题不同，放一个文档索引文件，补不齐接口本身的语义。

节选里的退款示例很具体：把 post_refunds_1 改成表达动作的名称，并说明适用于已扣款支付、待授权支付该用哪个操作、金额单位是什么，以及省略金额如何处理。描述的价值在于交代使用条件和相邻操作的边界。

作者还给出两段排查命令：用 jq 统计缺少 description 的操作，再配合 grep 筛出缺失或带有机械生成特征的 operationId。后者只是定位可疑名称，不能自动判定接口质量；前者也查不出「字段存在但内容空泛」。

我的判断

对程序员来说，优先补清工具的适用条件，比单纯把描述写长更有用。

退款与撤销授权这类相近操作，尤其需要明确区分。参数类型能约束输入格式，却不能独自解释业务前提；接入智能体时，这部分知识需要进入它实际能读到的工具定义。

不过，72% 衡量的是实验中的选择偏好，不能据此推导调用成功率。节选未交代完整实验设置，20% 基线的构造方式也不清楚，尚不足以量化项目收益。

另外，示例中的安全重试依赖服务端确实实现幂等语义。描述应准确反映已有行为，文字和注解本身不会让接口具备这项能力。