Tool Design for Models：为什么工具应该为模型设计，而不是为人

传统 API 设计追求对人友好——精简、直观、优雅。但 LLM 调用工具的方式和人完全不同。给模型设计的工具需要的是"认知负担最小化"而非"接口优雅"。本文从第一性原理拆解两者的根本差异。

工具体验的两条路

你写了一个函数给同事用。你会追求函数名自文档化、参数少、返回值干净。这是常识——API 设计的原则大多站在调用者的视角。

现在这个调用者变成了 GPT-4。同样的函数，同样的设计原则，表现却忽好忽坏。

问题不在模型不够聪明，在于"对人不友好的接口，对模型往往也不友好"这个直觉是错的。真正的情况是：人对 API 的舒适区和模型对 API 的舒适区，在两个完全不同的坐标系里。

坐标系的根源

人调用函数时会做什么？读文档、看示例、理解参数语义、猜测返回值格式。人有一个巨大的缓存空间——大脑的工作记忆虽然有限，但人可以"慢慢想"、"来回翻文档"、"写测试代码试错"。人的认知负载瓶颈不在单次调用，而在理解和记忆整个接口。

模型调用函数时在做什么？在一个固定的上下文窗口中，一次性看完所有工具定义 + 对话历史 + 当前输入，然后做一次前向推理。模型没有"回头翻文档"的能力（除非你把文档也塞进上下文），没有"先写个测试"的试错机会，更没有"慢慢想"的奢侈——每一步推理的 token 都计入成本。

所以关键差异浮出水面了：

人的瓶颈是理解接口的结构。模型的瓶颈是在上下文中定位到正确的信息。

为什么"干净接口"可能有害

传统 API 设计推崇 DRY——一个参数有多种含义？拆成两个函数。返回值有冗余字段？精简。参数名要简短优雅。

对模型来说，这套原则反过来才是对的。

冗余不是浪费，是信号。 同一个信息在工具描述、参数名、示例中重复出现，对人是多余的噪音，但对模型是多重确认——它让模型在注意力分布中更容易命中关键信息。HumanEval 实验已经证明，给函数加上自然语言注释比只给函数签名 + 参数类型，模型通过率高 30% 以上。

明确比优雅重要。 参数名 temperature 对人来说很直观，但对模型不一定。如果模型在训练数据中见过 temperature 和"控制输出的随机性"同时出现的频率足够高，它就能理解。但如果一个自定义工具的某个参数叫 mode，描述写的是"处理模式"，模型大概率会困惑——mode 可以是一切。把描述写成"mode=strict 时拒绝匹配度低于 0.8 的结果，mode=lax 时接受所有结果"，模型理解起来的成本就低很多。

返回值要结构化到"一眼就能看出来"。 模型不会像人一样"扫一眼 JSON 找到需要的字段"。模型是在做序列预测——它需要最频繁被访问的字段出现在最显眼的位置。所以 {status: "ok", data: {...}, error: null} 比 {data: {...}} 更友好，即使后者更"干净"。

工具描述是注意力引导器

大多数人写工具描述时，把它当成了"写给开发者看的文档"。但工具描述的唯一读者是模型（对于 function calling 场景，用户不直接看工具定义）。

一个被低估的事实是：工具描述的长度和精确度的关系不是线性的。太短的描述（"获取天气信息"）模型不知道参数怎么填。太长的描述（把文档复制进去）稀释了关键点的信号。

最佳实践是：开头一句话说清楚工具做什么，后面分段说清楚参数怎么用，每段只覆盖一个逻辑单元。

Anthropic 的 Claude function calling 文档里有个很好的例子——工具描述里包含参数的格式约束（"YYYY-MM-DD"的日期格式、大写字母的组织代码等）。人看可能觉得啰嗦，但对模型来说，这些约束减少了它猜测格式的范围。

错误信息也是工具接口的一部分

这是最容易被忽视的。工具返回的错误信息，人会看，然后改代码。但模型会在同一轮对话中看到错误信息，并尝试修正调用。

所以工具返回的错误信息应该设计成"给模型看的诊断报告"——明确指出哪里错了、期望的格式是什么、可以怎么调。而不是"给开发者看的错误码"。

举例：
- ❌ {"error": "E4001", "message": "Invalid parameter"}
- ✅ {"error": "date_from 格式不正确，期望 YYYY-MM-DD，收到 '2024/3/15'"}

前者让人去查文档。后者让模型可以直接修正并重试。

写在最后

工具设计哲学的核心转移是从"怎样设计一个漂亮的接口"到"怎样降低模型在每次调用时的认知负载"。这套思路和传统 API 设计的大多数原则是正交的——甚至是对立的。

一个好的模型工具应该：
- 参数名 + 描述 = 能让模型"一眼看懂"这个参数控制什么
- 返回值明确标记状态和关键字段的位置
- 错误信息直接告诉模型该怎么修正
- 适度的信息冗余，而不是极致的 DRY

把工具当成模型的认知辅助，而不是人的开发体验。