# Хорошее описание инструмента

Курс: MCP: подключаем инструменты — https://zero2claude.ru/learn/mcp
Канонический URL: https://zero2claude.ru/learn/mcp/3-2-horoshee-opisanie

Хорошее описание tool говорит модели, когда его звать и какие данные передать. Сравниваем сухой и переписанный вариант.

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

## Было

```
name: "task"
description: "Работа с задачами."
```

Что здесь не так? «Работа с задачами» — это создать, найти, закрыть, удалить? Модель не понимает границ. При двух-трёх похожих инструментах она начнёт путаться, какой звать.

## Стало

```
name: "find_task"
description: "Найти ОДНУ задачу в трекере по её номеру и вернуть \
  заголовок, статус и исполнителя. Использовать, когда пользователь \
  называет конкретный номер задачи. НЕ создаёт и не меняет задачи."
input_schema:
  number: integer  # номер задачи, например 412
```

## Что делает описание хорошим

- **Одно действие — один инструмент.** `find_task` ищет, и только. Создание — отдельный инструмент со своим именем.
- **Сказано, КОГДА звать.** «когда пользователь называет конкретный номер» — это подсказка модели, как выбрать.
- **Сказано, чего инструмент НЕ делает.** Явные границы спасают от ложных вызовов.
- **Описаны входы.** В схеме и в комментарии видно, что нужен номер, и приведён пример.

Пиши описание так, будто объясняешь новому сотруднику, который видит только эту строчку и больше ничего о системе не знает. Если ему было бы непонятно — модели тоже.

Хорошее описание — это не украшение. Это то, от чего напрямую зависит, попадёт ли Claude в нужный инструмент с первого раза.