Agent Tool Builder：写给所有 Agent 开发者的工具设计指南

写过 Agent 的人大概都踩过这个坑：工具明明写好了，AI 却总是调用失败、返回乱码、或者直接幻觉出一个不存在的功能。

问题大概率不在代码，而在工具描述。

最近在 Smithery 上发现了一个 Skill——Agent Tool Builder，专门教 AI 怎么设计好用的工具，视角非常独特，推荐给所有做 Agent 开发的朋友。

核心洞察：LLM 从来看不到你的代码

这个 Skill 的核心观点一针见血：LLM 从来看不见你的实现代码，它只看得见 Schema 和描述。

也就是说，哪怕你写了一个逻辑天衣无缝的工具，只要描述写得含糊——”这个函数用来处理数据”——AI 照样会调用失败。相反，一个实现简单的工具，只要描述精准，AI 就能稳定使用。

所以 Agent Tool Builder 花大量篇幅讲的不是代码怎么写，而是 JSON Schema 怎么搭、描述怎么写、错误怎么返回。

三个反直觉的设计原则

Skill 里列了几个常见反模式，值得所有 Agent 开发者对照自查：

1. 模糊描述比没有描述更危险

写”处理数据”不如写”接收一个 JSON 对象，其中必须包含 user_id 和 action 字段，返回该用户当前任务列表”。越具体，AI 越不会跑偏。

2. 静默失败是 Agent 的天敌

很多工具在出错时只返回空值或简单字符串。Agent Tool Builder 建议：返回结构化的错误信息，告诉 AI 哪里出了问题、可能的原因是什么、下一步可以怎么恢复。

3. 工具不是越多越好

Skill 明确列出了”Too Many Tools”作为反模式。工具太多会让 AI 难以选择，还容易产生干扰调用。质量 > 数量。

如何安装使用

npx skills add https://github.com/davila7/claude-code-templates --skill agent-tool-builder

安装后，当你想让 AI 帮你设计或审查一个工具时，这个 Skill 会自动激活，给出 Schema 建议、描述优化方向、以及错误处理方案。

配合 multi-agent-orchestration、api-designer 等相关 Skill 使用效果更佳。

这个 Skill 来自 davila7/claude-code-templates 仓库（⭐ 24.4K），在 Smithery 上有 500+ 次安装，2026 年 1 月首次发布，属于经过社区验证的实用工具。

如果你正在做 Agent 开发，或者经常需要给 AI 设计工具调用接口，这个 Skill 值得装上试试。

GitHub：https://github.com/davila7/claude-code-templates

GitHub: https://github.com/davila7/claude-code-templates