# Инструменты (tools)

Функции, которые вызывает модель

> Страница сайта MCP Docs — неофициального перевода документации Model Context Protocol (https://mcpdocs.ru/concepts/tools/). Тип: Перевод и пересказ. Основа: Спецификация, раздел «Tools» (https://modelcontextprotocol.io/specification/2026-07-28/server/tools). Ревизия спецификации 2026-07-28, сверено 05.10.2026.

Сервер может открыть инструменты, которые вызывает языковая модель: запросы к базам данных, вызовы API, вычисления. Каждый инструмент однозначно определяется именем и содержит метаданные со схемой.

## Модель управления

Инструменты рассчитаны на **управление моделью**: модель сама находит и вызывает их, исходя из контекста и запросов пользователя. Но протокол не навязывает интерфейс.

> **Важно.** Ради безопасности у человека СЛЕДУЕТ быть возможность отклонить вызов. Приложениям СЛЕДУЕТ показывать, какие инструменты открыты модели, явно отмечать вызовы и просить подтверждения для операций.

## Возможности сервера

Сервер, который поддерживает инструменты, ДОЛЖЕН объявить возможность `tools`:

```json
{
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  }
}
```

`listChanged` показывает, пришлёт ли сервер уведомление при изменении перечня инструментов.

Перечень, который сервер отдаёт в ответ на `tools/list`, МОЖЕТ быть пустым и МОЖЕТ меняться со временем, но НЕ ДОЛЖЕН зависеть от соединения или от побочных эффектов других запросов. Он МОЖЕТ различаться в зависимости от переданной авторизации: например, можно вернуть только те инструменты, которые разрешены выданными правами. Порядок инструментов СЛЕДУЕТ делать детерминированным: так клиенту проще кэшировать перечень, а у модели выше шанс попасть в кэш подсказки.

## Сообщения

### Список инструментов

Операция поддерживает постраничную выдачу и кэширование.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "tools": [
      {
        "name": "get_weather",
        "title": "Weather Information Provider",
        "description": "Get current weather information for a location",
        "inputSchema": {
          "type": "object",
          "properties": {
            "location": { "type": "string", "description": "City name or zip code" }
          },
          "required": ["location"]
        }
      }
    ],
    "nextCursor": "next-page-cursor",
    "ttlMs": 300000,
    "cacheScope": "public"
  }
}
```

### Вызов инструмента

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "location": "New York" }
  }
}
```

Ответ несёт `content` (массив элементов) и признак `isError`:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resultType": "complete",
    "content": [
      { "type": "text", "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy" }
    ],
    "isError": false
  }
}
```

В примерах опущены поля `_meta`, но каждый запрос ДОЛЖЕН включать обязательные поля. Подробнее: [«Протокол»](https://mcpdocs.ru/protocol/#polya-meta).

### Недостаточно данных

Сервер МОЖЕТ ответить на `tools/call` результатом `input_required`, если для вызова нужны дополнительные данные. Клиент собирает их и повторяет вызов с полем `inputResponses` и, если сервер его прислал, с `requestState`. Идентификатор JSON-RPC у повторного запроса ДОЛЖЕН отличаться от идентификатора первого. Механизм описан на странице [«Шаблоны обмена»](https://mcpdocs.ru/protocol/patterns/#mnogoshagovye-zaprosy-mrtr).

### Уведомление об изменении перечня

Серверу, объявившему `listChanged`, СЛЕДУЕТ отправлять `notifications/tools/list_changed` клиентам, которые открыли поток `subscriptions/listen` с фильтром `toolsListChanged: true`.

## Поля Tool

| Поле | Описание |
| --- | --- |
| `name` | Уникальное имя инструмента. |
| `title` | Необязательное название для показа человеку. |
| `description` | Описание функциональности для человека. |
| `icons` | Необязательные значки для интерфейсов. |
| `inputSchema` | Схема JSON Schema ожидаемых параметров. По умолчанию действует 2020-12, и это ДОЛЖЕН быть корректный объект схемы (не `null`). |
| `outputSchema` | Необязательная схема структуры результата. |
| `annotations` | Необязательные свойства, описывающие поведение инструмента. Клиенты ДОЛЖНЫ считать аннотации недоверенными, если они не пришли от доверенного сервера. |

Для инструмента без параметров рекомендуется схема `{ "type": "object", "additionalProperties": false }`.

### Имена

- Длина имени СЛЕДУЕТ составлять от 1 до 128 символов.
- Регистр СЛЕДУЕТ учитывать.
- Допустимые символы СЛЕДУЕТ ограничить латинскими буквами, цифрами, подчёркиванием (`_`), дефисом (`-`) и точкой (`.`).
- Пробелы, запятые и другие спецсимволы НЕ СЛЕДУЕТ использовать.
- Имя СЛЕДУЕТ делать уникальным в пределах сервера.

Уникальность ограничена одним сервером. Клиенты и прокси, которые собирают инструменты с нескольких серверов, СЛЕДУЕТ реализовать способ различения, например приставку с идентификатором сервера. Название сервера из `serverInfo` для этого не годится: оно не гарантирует уникальности.

### Заголовки из параметров (`x-mcp-header`)

Сервер МОЖЕТ пометить параметр инструмента свойством `x-mcp-header`. Тогда клиент при работе по Streamable HTTP ДОЛЖЕН продублировать значение в заголовок `Mcp-Param-{имя}`. Это позволяет балансировщикам и прокси направлять запросы по значению параметра, не разбирая тело. Ограничения и кодирование значений описаны на странице [«Транспорты»](https://mcpdocs.ru/protocol/transports/#zagolovki-iz-parametrov-instrumenta). Чувствительные параметры (пароли, ключи, токены, персональные данные) помечать так НЕ СЛЕДУЕТ: заголовки видны посредникам.

## Результаты

Результат может быть неструктурированным (`content`) или структурированным (`structuredContent`).

| Тип содержимого | Назначение |
| --- | --- |
| `text` | Текст. |
| `image` | Изображение в base64 с типом MIME. |
| `audio` | Аудио в base64 с типом MIME. |
| `resource_link` | Ссылка на ресурс, который клиент может прочитать или на который подписаться. В `resources/list` такие ссылки могут не появиться. |
| `resource` | Встроенный ресурс с URI и содержимым. |

Все типы содержимого поддерживают необязательные аннотации (аудитория, приоритет, время изменения).

### Структурированный результат

`structuredContent` — любое значение JSON (объект, массив, строка, число, логическое значение или `null`). Если у инструмента есть `outputSchema`, сервер ДОЛЖЕН возвращать результат, который ей соответствует, а клиентам СЛЕДУЕТ проверять результат по схеме. Для обратной совместимости инструменту, который возвращает структурированный результат, СЛЕДУЕТ дублировать его сериализованным JSON в текстовом блоке.

> **Заметка переводчика.** `structuredContent` не связан со «структурированным выводом» моделей, то есть с генерацией по схеме. Это просто данные, которые вернул сервер.

## Инструменты с состоянием

В MCP нет сессий на уровне протокола, поэтому сервер не может опираться на неявное состояние соединения. Если инструменту нужно хранить состояние между вызовами (корзина, открытый браузер, транзакция), сервер возвращает явный **дескриптор** из инструмента создания и принимает его аргументом в последующих вызовах. Для протокола дескриптор — обычная строка. Это нормативно не регулируется, а спецификация даёт рекомендации.

- **Авторизация.** Для серверов с аутентификацией дескриптор лишь имя, и права нужно проверять при каждом вызове. Без аутентификации дескриптор фактически токен предъявителя, его нужно генерировать с достаточной энтропией (например, UUIDv4) и ограничить срок жизни.
- **Непрозрачность.** Дескрипторы с внутренней структурой провоцируют разбор и угадывание.
- **Срок жизни.** Правила хранения СЛЕДУЕТ указать в описании инструмента создания, например «корзины удаляются через 24 часа простоя».
- **Ошибка просроченного дескриптора.** Вызов с просроченным или неизвестным дескриптором СЛЕДУЕТ завершать ошибкой выполнения инструмента, чтобы модель могла создать новый.

## Ошибки

Есть два вида ошибок.

1. **Ошибки протокола** касаются структуры запроса, и модель вряд ли исправит их сама: неизвестный инструмент, некорректный запрос, сбой сервера. Они возвращаются как стандартные ошибки JSON-RPC, например с кодом `-32602`.
2. **Ошибки выполнения** содержат подсказки, по которым модель может исправиться и повторить: сбой API, неверный формат даты, значение вне диапазона, нарушение бизнес-логики. Они передаются в результате с `isError: true`.

Клиенты МОГУТ передавать модели ошибки протокола, а ошибки выполнения СЛЕДУЕТ передавать, чтобы модель могла исправиться.

## Безопасность

Серверы ДОЛЖНЫ проверять все входные данные инструментов, реализовывать контроль доступа, ограничивать частоту вызовов и очищать выходные данные. Клиентам СЛЕДУЕТ запрашивать подтверждение для чувствительных операций, показывать пользователю входные данные до вызова (чтобы не допустить утечки), проверять результаты перед передачей модели, ограничивать время вызова и вести журнал использования.