# 工具与质量 (/zh/docs/mcp-servers/tools-and-quality)

模型从不直接看到 MCP 服务器。它看到的是服务器的工具列表，在对话的每一轮发送，并转换成各提供商自己的格式。MCP 服务器页面上的**模型如何看待此服务器**卡片会按模型得到的样子显示这份列表：
它的开销、哪些工具开销最大，以及模型会弄错的名称、描述和 Schema。请在构建服务器时使用它，或者在把别人的服务器交给智能体之前使用。

一旦检查列出了至少一个工具，该卡片就会出现在**工具**下方。

<Shot id="mcp-quality-card" alt="Alpenglow MCP 的“模型如何看待此服务器”卡片：Anthropic、OpenAI 和 Google Gemini 的令牌数、最大的工具，以及“没有会让模型出错的地方”这一行" />

## 工具的开销 [#what-the-tools-cost]

卡片顶部给出工具列表在 **Anthropic**、**OpenAI** 和 **Google Gemini** 下每一轮占用的令牌数，按各提供商的格式计算。其下一行说明这是多少个工具，以及三者中最大的那个占 200k 上下文的比例。

这些数字是估计值，与各提供商的计数相差大约 15% 以内。它们适合用来比较服务器，以及观察修改描述或 Schema 会带来什么影响。

**最大的工具**列出开销最大的五个工具及其令牌数。只有一个工具的服务器不显示此列表。

## 模型会在哪里出错 [#what-a-model-would-stumble-over]

接下来是发现的问题列表，最严重的排在最前面。标题会统计它们的数量（例如 `1 problem, 2 warnings`），或者显示**没有会让模型出错的地方**。每一条发现都会指出工具、说明问题所在，并给出修复建议。

| 类型 | 含义 |
| --- | --- |
| 问题 | 提供商拒绝该工具，或模型只能猜测如何使用它。请先修复这些。 |
| 警告 | 它能用，但模型很可能选错工具或把参数填错。 |
| 备注 | 值得了解的情况，例如某个提供商会丢弃的约束。 |

Echolot 对每个工具检查的内容：

| 发现 | 类型 | 怎么做 |
| --- | --- | --- |
| 名称不是提供商接受的名称 | 问题 | 使用字母、数字、`_` 和 `-`，最多 64 个字符。Anthropic 和 OpenAI 会拒绝其余的。 |
| 没有描述 | 问题 | 说明工具做什么、需要什么以及返回什么。 |
| 描述几乎只是重复名称 | 警告 | 说明工具需要什么、返回什么，以及什么时候该用它而不是类似的工具。 |
| 很长的描述（超过 1,500 个字符） | 备注 | 每一轮都会重新读取它。 |
| 输入 Schema 不是对象 | 问题 | 每个提供商都要求 `{"type": "object", "properties": …}`。没有参数的工具写 `"properties": {}`。 |
| Schema 没有属性 | 备注 | 没有参数时写 `"properties": {}`，否则请描述现有的参数。 |
| 接受任何对象 | 警告 | 描述工具读取的属性，这样模型就不会凭空编造参数。 |
| 要求一个属性中没有定义的参数 | 问题 | 定义该属性，或将它从 `required` 中去掉。 |
| 参数没有类型 | 问题 | 为每个参数给出 `type`（或 `enum`）。否则模型只能猜，而 OpenAI 的严格模式会拒绝它。 |
| 自由格式的对象（没有属性） | 警告 | 描述其中的键，或在描述中说明该填什么。 |
| 参数没有描述 | 警告 | 每个参数一行：它是什么，并给一个示例值。 |
| 使用 `$ref` | 警告 | Gemini 会丢弃它，所以该参数在那里什么都接受；OpenAI 的严格模式要求内联展开。 |
| Gemini 会丢弃的关键字，例如 `oneOf`、`pattern` 或 `additionalProperties` | 备注 | 在 Gemini 下该约束会丢失。 |
| 很大的 Schema（超过约 1,000 个令牌） | 警告 | 拆分该工具，或将很少使用的选项移出 Schema。 |
| 超过 25 个参数 | 警告 | 拆分该工具，或将选项分组。 |
| 嵌套超过 5 层 | 警告 | 把参数展平；模型填写深层结构时表现很差。 |
| 枚举有超过 40 个值 | 备注 | 每个值每一轮都会被读取。 |

以及整个列表层面的检查：

| 发现 | 类型 | 怎么做 |
| --- | --- | --- |
| 模型会混淆的名称（忽略大小写、`_` 和 `-` 之后相同） | 问题 | 按区别于其他工具的特点来命名工具。 |
| 两个工具的描述相同 | 问题 | 说明它们的区别；模型是根据描述在工具之间做选择的。 |
| 两个描述说的内容大致相同（共有 60% 或更多的词） | 警告 | 在每个描述中说明什么时候该用它而不是另一个。 |
| 超过 128 个工具 | 问题 | OpenAI 拒绝超过 128 个。请提供更少的工具，或拆分服务器。 |
| 超过 40 个工具 | 警告 | 工具多了，模型的选择会变差。一次提供更少的工具，或按主题拆分服务器。 |
| 列表每一轮的开销超过 20,000 个令牌 | 警告 | 缩短描述和 Schema，或提供更少的工具。 |

更改服务器之后，请再次点按**检查**：卡片会跟随新的工具列表。

## 提供商收到的列表 [#the-list-as-a-provider-receives-it]

打开卡片底部的**提供商收到的列表**，并选取 **Anthropic**、**OpenAI** 或 **Google Gemini**。你会以 JSON 的形式看到该提供商的 API 收到的工具列表。**拷贝**会将它拷贝下来。
例如，在这里你可以看到 Gemini 的格式会从 Schema 中省略什么。

## 用模型试试 [#try-with-a-model]

下方的**用模型试试**卡片会询问真实的模型它会调用哪个工具。输入某人可能让智能体用这个服务器做的事，例如 `Is the two-person tent in stock?`，然后点按**试用**。

<Shot id="mcp-try-with-a-model" alt="“用模型试试”卡片：一条关于帐篷的提示词，以及模型的回答，即对 search_catalog 的一次调用及其参数" />

模型会看到服务器的工具，并回答它会进行的调用。不会真的调用任何内容。对于每次调用，你会看到工具及其参数；不符合工具 Schema 的参数会被标出，并说明问题所在。
不清楚的名称和描述就是这样暴露出来的。下方，Echolot 会显示使用的令牌数，对于它知道价格的模型，还会显示这一轮大约的费用。

该卡片使用在[设置 › 助手](/docs/ai/assistant)中选取的模型。没有选取时，它会提示你在那里选取模型提供商。你第一次试用时，Echolot 会询问是否可以将提示词和服务器的工具发送给该提供商；
设备端模型和你 Mac 上的服务器不会询问。

## 通过命令行 [#from-the-command-line]

`echolot mcp check --quality` 在终端中打印同样的报告，`--strict` 会让它在有问题时以退出码 1 失败，这样服务器的 CI 就可以让它的工具列表保持良好状态。`--as anthropic`、`--as openai` 或 `--as gemini`
只打印该提供商收到的列表。参见 [echolot mcp](/docs/cli/mcp)。

```sh
echolot mcp check --url https://demo.echolot.dev/mcp --quality
```