AI 速读
工具能跑通、Schema 正确，Agent 却总用错？问题出在你用写 API 的思维写工具。
越来越多的开发者开始为 AI Agent 开发工具：通过 MCP（Model Context Protocol）、Skills 脚本，或直接使用 OpenAI/Claude 的 function calling。但很快大家遇到一个令人困惑的现象：
CAUTION
**技术上实现完全正确的工具，Agent 却用不好。**工具能跑通，Schema 定义正确，API 调用成功，但 Agent 总是选错工具、传错参数，或者在明明应该调用工具的时候回复「我无法完成这个任务」。
这是 TRAE 团队在开发过程中持续思考的问题，也是这篇要拆解的核心。
问题出在哪里#
我们用写 API 的思维在写 Agent 工具。
为人类设计 API 时，可以假设开发者会阅读文档、理解上下文、在出错后调试代码。但 Agent 是完全不同的「用户」：
- 它只能通过工具的名称、描述和参数 Schema来「理解」这个工具能做什么；
- 它「试错」的代价很高——每次调用都消耗 Token，都可能影响用户体验；
- 它需要在可能几十上百个工具中瞬间做出选择；
- 它有一定的试错能力，但成本高且不稳定。
所以，给 Agent 开发工具的真正挑战不是技术实现，而是设计出 Agent 能用好的工具接口。
核心理念：Agent 工具是用户界面#
这里有一个关键的思维转换：
Agent 工具是 AI Agent 的用户界面（User Interface），不是已有 REST API 的封装。
你不是在写 API，你是在教一个智能体如何与世界交互。而这个智能体（LLM）有独特的长处与短板：
- 擅长：理解自然语言、推理意图、组合信息；
- 不擅长：精确计算、记住长上下文、从模糊描述猜测正确参数；
- 看不到你的代码实现，只能看到你暴露的 Schema 和描述；
- 只具备有限的上下文，且随着上下文被打满，工具调用性能会明显下降。
只有理解这个「用户」的特性，才能设计出它真正能用好的工具。
本文以 MCP 为主要切入点——它正在成为 Agent 工具开发的主流协议——但这些设计原则适用于所有 Agent 工具场景。
一个前置认知#
在动手设计之前，需要先理解工具是如何被 Agent「消费」的：LLM 原生 Tool Calling 的完整链路、工具定义在模型侧的真实形态、以及工具数量对效果的影响。下一篇将从调用链路一路讲到命名与描述的具体技巧。
出处
本文参考小夏《如何让你的 Agent 更准确：MCP 工具设计技巧（上）》（TRAE 公众号文章 ↗），对其中「Agent 工具即用户界面」的理念做了梳理与自己的理解。示例与数据归原作者。