# Tools: инструменты

> Инструменты MCP в редакции 2026-07-28 - tools/list и tools/call, схема параметров, результат и два вида ошибок, инструменты с состоянием и требования безопасности

Страница: https://mcpdoc.ru/protocol/tools/
Указатель сайта: https://mcpdoc.ru/llms.txt

Инструмент - функция сервера, которую может вызвать языковая модель: запрос к базе, обращение к API, расчёт. У инструмента есть имя, описание и схема параметров. Клиент получает список запросом `tools/list` и вызывает инструмент запросом `tools/call`.

описана редакция 2026-07-28, сверено со спецификацией 4 октября 2026

Источник - страница [Tools](https://modelcontextprotocol.io/specification/2026-07-28/server/tools) спецификации. В примерах ниже для краткости опущено поле `_meta`; в настоящем запросе оно [обязательно](https://mcpdoc.ru/protocol/stateless/).

## Кто решает, когда вызывать

Инструментами управляет модель: она сама выбирает инструмент по смыслу разговора. Протокол не предписывает интерфейс, но спецификация рекомендует, чтобы человек всегда мог отказать в вызове. Приложению следует показывать, какие инструменты доступны модели, отмечать момент вызова и спрашивать подтверждение.

## Объявление возможности

Сервер с инструментами обязан объявить возможность `tools`.

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

`listChanged` означает, что сервер будет сообщать об изменении списка.

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

```json title="Запрос"
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}
```

```json title="Ответ"
{
  "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"]
        }
      }
    ],
    "ttlMs": 300000,
    "cacheScope": "public"
  }
}
```

Правила для списка:

- список может быть пустым и может меняться со временем;
- список не должен зависеть от соединения и от других запросов по нему;
- список может зависеть от прав, с которыми пришёл запрос: например, сервер покажет только то, что разрешено выданными областями доступа;
- серверу следует возвращать инструменты в одном и том же порядке, пока набор не изменился: так клиент может кэшировать список;
- запрос поддерживает постраничную выдачу и кэширование: поля `ttlMs` и `cacheScope` в результате обязательны.

## Описание инструмента

| Поле | Что это |
|---|---|
| `name` | уникальное имя в пределах сервера |
| `title` | необязательное название для показа человеку |
| `description` | описание того, что делает инструмент |
| `inputSchema` | JSON Schema параметров; обязана быть объектом схемы, не `null` |
| `outputSchema` | необязательная JSON Schema результата |
| `annotations` | необязательные сведения о поведении инструмента |
| `icons` | необязательные значки |

Если в схеме нет поля `$schema`, она читается как JSON Schema 2020-12. Для инструмента без параметров спецификация рекомендует схему, которая принимает только пустой объект.

```json title="Инструмент без параметров"
{
  "name": "get_current_time",
  "description": "Returns the current server time",
  "inputSchema": { "type": "object", "additionalProperties": false }
}
```

**Имена.** Имени следует быть длиной от 1 до 128 знаков и состоять из латинских букв, цифр, подчёркивания, дефиса и точки. Регистр букв следует считать значимым. Уникальность действует в пределах одного сервера: если клиент собирает инструменты с нескольких серверов, ему следует самому разводить совпадающие имена, например приставкой.

**Аннотации.** Клиент обязан считать аннотации ненадёжными, если они получены не от доверенного сервера. Подробнее - на странице [«Отравление инструментов»](https://mcpdoc.ru/security/threats/).

## Вызов

```json title="Запрос"
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "location": "New York" }
  }
}
```

```json title="Ответ"
{
  "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
  }
}
```

Сервер может ответить не готовым результатом, а просьбой о дополнительных данных (`resultType: "input_required"`). Тогда клиент собирает данные и повторяет вызов - см. [«Многошаговые запросы»](https://mcpdoc.ru/protocol/mrtr/).

## Что бывает в результате

Поле `content` - список блоков. Допустимые типы блоков:

| Тип | Содержимое |
|---|---|
| `text` | текст |
| `image` | изображение в Base64 и его MIME-тип |
| `audio` | звук в Base64 и его MIME-тип |
| `resource_link` | ссылка на [ресурс](https://mcpdoc.ru/protocol/resources/), который клиент может прочитать отдельно |
| `resource` | ресурс, вложенный прямо в результат |

Поле `structuredContent` несёт структурированный результат - любое значение JSON. Если у инструмента есть `outputSchema`, сервер обязан возвращать результат, который ей соответствует, а клиенту следует его проверять. Для совместимости серверу следует дублировать структурированный результат текстом в блоке `text`.

## Два вида ошибок

| Вид | Как приходит | Примеры | Что делать клиенту |
|---|---|---|---|
| ошибка протокола | обычная ошибка JSON-RPC | неизвестный инструмент, некорректный запрос, сбой сервера | модели можно показать, но исправить её она вряд ли сможет |
| ошибка выполнения | результат с `isError: true` | отказ внешнего API, дата в неверном формате, нарушение правила | следует показать модели: она может исправить параметры и повторить |

```json title="Ошибка выполнения"
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "resultType": "complete",
    "content": [
      { "type": "text", "text": "Invalid departure date: must be in the future. Current date is 08/08/2025." }
    ],
    "isError": true
  }
}
```

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

Сессий в протоколе нет, поэтому сервер не может связать два вызова «по соединению». Рекомендация спецификации (она не является требованием): инструмент, создающий состояние, возвращает явный идентификатор, и следующие вызовы принимают его как обычный аргумент.

```jsonc title="Корзина как пример"
// вызов
{ "name": "create_basket", "arguments": {} }

// результат
{
  "content": [{ "type": "text", "text": "Created basket bsk_a1b2c3" }],
  "structuredContent": { "basket_id": "bsk_a1b2c3" }
}

// следующий вызов
{ "name": "add_item", "arguments": { "basket_id": "bsk_a1b2c3", "sku": "..." } }
```

Советы спецификации к таким идентификаторам:

- на сервере с авторизацией идентификатор - это имя, а не право доступа: права вызывающего проверяются при каждом вызове;
- на сервере без авторизации идентификатор стоит делать непредсказуемым и ограничивать срок его жизни;
- срок хранения стоит написать в описании инструмента, чтобы модель его видела;
- на вызов с просроченным идентификатором стоит отвечать понятной ошибкой выполнения.

## Изменение списка

Серверу, объявившему `listChanged`, следует присылать уведомление `notifications/tools/list_changed` тем клиентам, которые открыли поток `subscriptions/listen` и попросили об этом.

## Требования безопасности

Раздел Security Considerations спецификации.

Сервер обязан:

- проверять все входные данные инструмента;
- разграничивать доступ;
- ограничивать частоту вызовов;
- очищать результат перед выдачей.

Клиенту следует:

- спрашивать подтверждение для чувствительных операций;
- показывать пользователю параметры до вызова, чтобы данные не утекли незаметно;
- проверять результат, прежде чем отдавать его модели;
- ставить вызовам предельное время;
- вести журнал вызовов.

Параметры, помеченные `x-mcp-header`, попадают в заголовки HTTP и видны промежуточным узлам. Секреты и персональные данные так помечать не следует. Как работает эта пометка, описано на странице [«Транспорты»](https://mcpdoc.ru/protocol/transports/).