# Инструменты и качество (/ru/docs/mcp-servers/tools-and-quality)

Модель никогда не видит MCP-сервер. Она видит список инструментов сервера, который отправляется с каждым ходом разговора
и преобразуется в формат каждого провайдера. Карточка **Как модель видит этот сервер** на странице «MCP-серверы»
показывает этот список в том виде, в каком его получает модель: сколько он стоит, какие инструменты стоят больше всего
и какие имена, описания и схемы модель поймёт неверно. Используйте её, пока пишете сервер или прежде чем отдать чужой
сервер агенту.

Карточка появляется под **Инструменты**, как только проверка перечислила хотя бы один инструмент.

<Shot id="mcp-quality-card" alt="Карточка «Как модель видит этот сервер» для Alpenglow MCP: число токенов для Anthropic, OpenAI и Google Gemini, самые крупные инструменты и строка «Модели не обо что споткнуться»" />

## Сколько стоят инструменты [#what-the-tools-cost]

Вверху карточки указано, сколько токенов занимает список инструментов у **Anthropic**, **OpenAI** и **Google Gemini** на
каждом ходу, посчитанных в формате каждого провайдера. Под ним строка сообщает, сколько это инструментов и какую долю
контекста в 200 тысяч токенов занимает самый большой из трёх результатов.

Числа — оценки, в пределах примерно 15 % от того, что считают провайдеры. Они годятся, чтобы сравнивать серверы и
видеть, что делает изменение описания или схемы.

**Самые крупные инструменты** перечисляет пять самых дорогих инструментов с их токенами. У сервера с одним
инструментом этот список опускается.

## Обо что модель могла бы споткнуться [#what-a-model-would-stumble-over]

Дальше идёт список замечаний, самые серьёзные первыми. Заголовок считает их (например, `1 problem, 2 warnings`) или
гласит **Модели не обо что споткнуться**. Каждое замечание называет инструмент, говорит, что не так, и предлагает
исправление.

| Вид | Значение |
| --- | --- |
| Проблема | Провайдер отклоняет инструмент или модель может лишь гадать, как им пользоваться. Исправляйте в первую очередь. |
| Предупреждение | Работает, но модель, вероятно, выберет не тот инструмент или плохо заполнит аргументы. |
| Заметка | Стоит знать, например ограничение, которое один из провайдеров отбрасывает. |

Что Echolot проверяет в каждом инструменте:

| Замечание | Вид | Что делать |
| --- | --- | --- |
| Имя, которое провайдер не принимает | Проблема | Используйте буквы, цифры, `_` и `-`, не больше 64 символов. Anthropic и OpenAI отклоняют остальное. |
| Нет описания | Проблема | Скажите, что инструмент делает, что ему нужно и что он возвращает. |
| Описание говорит немногим больше имени | Предупреждение | Скажите, что инструменту нужно и что он возвращает, и когда использовать его, а не похожий инструмент. |
| Длинное описание (больше 1500 символов) | Заметка | Оно перечитывается на каждом ходу. |
| Схема входных данных — не объект | Проблема | Каждому провайдеру нужно `{"type": "object", "properties": …}`. Инструмент без параметров пишет `"properties": {}`. |
| У схемы нет свойств | Заметка | Напишите `"properties": {}`, если параметров нет, или опишите те, что есть. |
| Принимает любой объект | Предупреждение | Опишите свойства, которые читает инструмент, чтобы модель не придумывала аргументы. |
| Требует параметр, который не определён в свойствах | Проблема | Определите свойство или уберите его из `required`. |
| Параметры без типа | Проблема | Дайте каждому `type` (или `enum`). Иначе модель гадает, а строгий режим OpenAI отклоняет. |
| Свободные объекты (без свойств) | Предупреждение | Опишите ключи или скажите в описании, что в них кладут. |
| Параметры без описания | Предупреждение | По одной строке на каждый: что это и пример значения. |
| Использует `$ref` | Предупреждение | Gemini его отбрасывает, поэтому параметр принимает что угодно; строгому режиму OpenAI нужно подставить содержимое прямо в схему. |
| Ключевые слова, которые отбрасывает Gemini, такие как `oneOf`, `pattern` или `additionalProperties` | Заметка | С Gemini ограничение теряется. |
| Большая схема (больше примерно 1000 токенов) | Предупреждение | Разделите инструмент или вынесите редко используемые параметры из схемы. |
| Больше 25 параметров | Предупреждение | Разделите инструмент или сгруппируйте параметры. |
| Вложенность глубже 5 уровней | Предупреждение | Упростите аргументы; модели плохо заполняют глубокие структуры. |
| Enum больше чем с 40 значениями | Заметка | Каждое значение читается на каждом ходу. |

И для списка в целом:

| Замечание | Вид | Что делать |
| --- | --- | --- |
| Имена, которые модель спутала бы (одинаковые, если игнорировать регистр, `_` и `-`) | Проблема | Называйте инструменты по тому, чем они отличаются. |
| Два инструмента с одинаковым описанием | Проблема | Скажите, чем они отличаются; модель выбирает между инструментами по их описаниям. |
| Два описания, говорящие почти одно и то же (60 % слов и больше общие) | Предупреждение | Скажите в каждом, когда использовать именно его, а не другой. |
| Больше 128 инструментов | Проблема | OpenAI отклоняет больше 128. Предлагайте меньше или разделите сервер. |
| Больше 40 инструментов | Предупреждение | Среди многих модель выбирает хуже. Предлагайте меньше за раз или разделите сервер по темам. |
| Список стоит больше 20 000 токенов на ход | Предупреждение | Сократите описания и схемы или предлагайте меньше инструментов. |

После изменения сервера нажмите **Проверка** снова: карточка следует за новым списком инструментов.

## Список в том виде, в каком его получает провайдер [#the-list-as-a-provider-receives-it]

Откройте **Список в том виде, в каком его получает провайдер** внизу карточки и выберите **Anthropic**, **OpenAI** или
**Google Gemini**. Вы увидите список инструментов таким, каким его получает API этого провайдера, в виде JSON.
**Скопировать** копирует его. Здесь видно, например, что формат Gemini оставляет за пределами схемы.

## Попробовать с моделью [#try-with-a-model]

Карточка **Попробовать с моделью** ниже спрашивает настоящую модель, какой инструмент она вызвала бы. Введите, о чём
кто-нибудь мог бы попросить агента с этим сервером, например `Is the two-person tent in stock?`, и нажмите
**Попробовать**.

<Shot id="mcp-try-with-a-model" alt="Карточка «Попробовать с моделью»: запрос о палатке и ответ модели — вызов search_catalog с его аргументами" />

Модель видит инструменты сервера и отвечает вызовами, которые она сделала бы. Ничего не вызывается. Для каждого вызова
вы видите инструмент и его аргументы; аргументы, которые не подходят к схеме инструмента, отмечены с указанием, что не
так. Так проявляются неясные имена и описания. Ниже 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
```