一、先破除一个误会#

我以前一直以为，模型「自己会调 API」。真相是：模型啥都没执行，它只是「开口申请」了一句。

用一句话概括就是：模型负责「说」，程序负责「做」。

二、协议层到底发生了什么（四步）#

把 SDK 那层遮羞布掀开，其实就这么回事：

第 1 步  你：这是可用的工具清单（名字 / 作用 / 参数）
第 2 步  模型：我要调用 search_web，参数 query=今天上海天气
第 3 步  你的程序：真的去调用，拿到结果
第 4 步  你：把结果还给模型，它接着推理或给出最终答案

看懂这段的关键在于：这四步里，模型只参与了第 2 步。

所以我后来养成了一个习惯：工具调用一出问题，先别骂模型笨，先回头看自己「说」得够不够清楚。

三、一个工具的三件套#

不管什么框架，一个工具定义扒开就三样东西：

四、描述，是 90% 的功夫#

这里我要敲黑板：模型看不到你的源码，也看不到函数体。它关于这个工具的全部认知，就来自那几行文字。

对比一下坏描述和好描述的区别：

坏：搜索文档

好：搜索内部文档库，返回最相关的 5 段。当用户问技术问题、
    API 用法、配置项时使用；闲聊和问个人数据时不要用。
    query 要具体，比如写「如何配置 autovacuum」而不是只写「vacuum」。

经验法则：如果一个工具描述你 50 个字就写完了，那多半还没写到位。 一条好描述通常包含三块——它是干吗的、什么时候用（正例和反例）、参数怎么填。

五、参数设计的几个小心机#

• 能不给参数就不给：参数越多，填错概率越大。
• 优先用枚举（enum）：只有几个合法值时，把它限死，别让模型自由发挥。
• 给默认值：大多数场景用默认就够，别逼它每次都做选择。
• 一个工具只干一件事：别写「万能工具」，模型会不知道该啥时候用它。
• 命名要有边界：像 notification_send_user 和 notification_send_channel 这种近义名，是选错工具的重灾区。

六、让输出更听话：严格模式#

现在主流两家都支持「严格模式」：一旦开启，可以保证模型吐出来的参数，和你给的 schema 严丝合缝。

一句话建议：schema 定义得越清楚，就越该把严格模式打开。 能省下不少半夜 debug 的眼泪。

七、工具一多，上下文就先喊救命了#

这是个很多人没意识到的隐形开销：工具定义本身就吃 token。

Anthropic 举过一个真实例子：接 5 个 MCP 服务（GitHub、Slack、Sentry、Grafana、Splunk），光这 58 个工具的定义，就要吃掉大约 5.5 万 token——对话还没开始，上下文先少了一大截。 他们甚至见过工具定义占掉 13.4 万 token 的情况。

解决办法之一是「按需发现」：不再一口气把所有工具塞进去，而是让模型先用一个「找工具的工具」去搜，只加载当前任务真正用到的那几个。官方数据是上下文占用能降约 85%。

八、报错，其实是正常流程的一部分#

工具一定会失败：超时、参数写错、结果为空。我的三条铁律：

1. 把错误当成正常结果返回给模型，别直接抛异常。这样它知道「这步挂了」，能换个姿势重试。
2. 给能操作的错误信息：返回「缺少参数 city」，比返回「Error 400」有用一百倍。
3. 一定要设重试上限：否则模型可能在「失败—重试—失败」里无限打转，这是我烧掉最多额度的一次教训。

九、一句话总结#

工具调用不是让模型变聪明，而是给模型装上了一双手。而这双手好不好用，取决于你把工具描述得够不够清楚。

下一篇写「记忆」，也就是怎么让 Agent 别聊两句就把前面忘光。

参考资料#

• Anthropic：Writing effective tools for agents — https://www.anthropic.com/engineering/writing-tools-for-agents
• Anthropic：Advanced tool use on the Claude Developer Platform — https://www.anthropic.com/engineering/advanced-tool-use
• Tool Use — The Agentic AI Field Guide — https://menuagentic.com/field-guide/tool-use/