为什么你的AI Agent总在瞎调用工具？看完这个Skill才明白问题在哪

为什么你的 AI Agent 总是在瞎调用工具？

我见过太多团队在 LLM Agent 项目里花了大量时间优化后端代码——结果模型就是不用他们的工具，或者调错了参数，或者直接陷入死循环。

然后他们开始怀疑模型不行、Prompt 不够好、或者框架选错了。

但我见过最根深蒂固的问题，其实是：你的工具设计本身就有问题。

一个真实的反常识事实：LLM 从来不看你写的代码。它只看你暴露给它的 schema 和 description。所以一个实现完美的工具，如果 description 写得模棱两可，它照样会失败；而一个简单到极致的工具，只要 description 清晰，LLM 就能完美调用它。

这个洞察来自 Smithery 推出的一个专注于”AI 工具设计”的 Skill——Agent Tool Builder。

三个让 Agent 稳定工作的核心设计模式

这个 Skill 没有花哨的框架或复杂的代码。它只做一件事：教你如何写出 LLM 能看懂的工具描述。

模式一：Tool Schema Design——JSON Schema 写对了，LLM 才能调对

工具的参数 schema 不是给开发者的，是给 LLM 的说明文档。你要写得足够精确，但不能过于复杂。描述里要说明”什么时候该调用这个工具”，而不仅仅是”这个工具叫什么”。

模式二：Tool with Input Examples——给例子，准确率提升 25%

在 description 里加 2-3 个实际调用示例。LLM 看到具体例子后，对参数格式和约束条件的理解会显著提升。这个改动成本为零，但效果有文献支撑。

模式三：Tool Error Handling——错误信息要能指导 LLM 恢复，而不是让它蒙圈

很多工具出错了就直接抛异常，LLM 拿到一个错误码完全不知道发生了什么。好的做法是返回一个结构化的错误信息，告诉 LLM：哪里出了问题、可能的原因是什么、下一步可以怎么修复。

三个致命的反模式

• ❌ Vague Descriptions：description 里只写了工具名，没写什么时候该用、什么时候不该用
• ❌ Silent Failures：工具执行失败了但不返回任何内容，直接 return null，LLM 完全不知道发生了什么
• ❌ Too Many Tools：一个 Agent 挂了几十个工具，LLM 每次要从几十个选项里选，压力一大就开始乱选

怎么用这个 Skill？

在 Smithery 的 Skill 市场可以直接安装到你的 Claude Code 或兼容的 AI Agent 环境：

npx skills add https://github.com/smithery/ai --skill agent-tool-builder

安装后，它会自动指导你编写和审查任何新增的工具 schema。在动手写代码之前先过一遍它的 Checklist，能显著减少 Agent 运行时的调试时间。

这个 Skill 的本质逻辑很直接：Description quality > implementation quality for LLM accuracy。在 AI Agent 场景里，工具的”说明书”比工具的”实现”更重要。

总结

如果你在做 LLM Agent 开发，遇到过 Agent 乱调用工具、参数传错、或者执行后没有正确反馈结果的问题——别急着改 Prompt 或换模型。先花 20 分钟审视一下你的工具 schema 设计。

很多问题的根源，不在模型，不在框架，在于给模型看的那份”工具说明书”本身。

GitHub：https://github.com/smithery/ai

GitHub: https://github.com/smithery/ai