Редакция 3 августа 2026 г.

Перестаньте писать описания MCP-инструментов так, будто их читает человек

Соло на Cursor с парой MCP-серверов знакома картина: агент уверенно выбирает инструмент, а на выходе — неверный идентификатор пользователя или пустой ответ, хотя схема параметров на месте. В разборе Renato Marinho сдвигает фокус с модели на метаданные: описания часто пишут «для коллеги», а не для парсера агента — и именно там сидит типичный сбой агентного сценария.

Когда «вежливое» описание ломает вызов

Описания MCP-инструментов — не маркетинговый абзац. Marinho сравнивает их с архитектурой набора инструкций на естественном языке: каждое лишнее предложение до императива — шум в окне контекста и выше риск сбоя рассуждения. Агентам, по его формулировке, не нужна вежливость — им нужна плотность смысла.

Типичный «плохой» текст выглядит так:

This tool allows you to fetch user information from our database and will return the details as a string.

После такого описания агент может передать user_id, хотя параметр назван userId; «забыть», что выход — строка, потому что тип ответа не сформулирован как приказ; утонуть в «лишней воде» вместо выбора нужного инструмента.

Плотность смысла, глаголы и оценщик

Плотность смысла — отношение прикладной информации к длине текста. Пассив, обороты вроде «is designed to help you…» и несколько предложений контекста до глагола действия снижают соотношение плотности: агент тратит окно контекста на шум.

В «хороших» описаниях Marinho выделяет императивы — retrieve, update, delete, fetch, calculate; явные типы возврата («returns a string» / «returns an object»); единый стиль написания имён на весь список параметров. Строка «Retrieve the record and then update it» названа высокоплотной; для неё в тестах автора доля императивных глаголов примерно 0,28 — единственное количественное значение в методике.

Для измерения упоминается Tool Description Semantic Density Scorer и три функции:

Функция	Назначение
`calculate_verb_encensity`	Доля императивных, ориентированных на действие глаголов vs проза и пассив
`analyze_naming_uniformity`	Аудит стиля имён параметров (`camelCase` vs `snake_case`)
`evaluate_description_clarity`	Агрегат: плотность глаголов + единообразие имён + явные типы возврата

Готовых JSON MCP-инструментов или fenced code blocks с определениями в материале нет — только нарратив, названия функций оценщика и качественные критерии.

Имена параметров — тихий убийца JSON

Несогласованность имён (user_id vs userAge) для языковой модели при сборке JSON — тревожный сигнал и сбои разбора на следующих шагах. analyze_naming_uniformity флагает «отклоняющийся» параметр, если один элемент выпадает из общего стиля.

Практический вывод: проверять определения инструментов с той же строгостью, что типы в TypeScript — стиль имён, плотность глаголов, явные типы возврата. Пока описание читается как FAQ для человека, агент будет ошибаться в параметрах даже при «сильной» модели.

Где это бьёт по Cursor и соло-стеку

Claude Desktop, Cursor и Windsurf в материале названы средами, куда подключают MCP и где проявляются ошибки из-за размытых описаний. Для соло-разработчика без отдельного контроля качества метаданные инструментов — узкое место: не языковая модель «тупит», а набор инструкций на естественном языке сформулирован размыто.

Сравнительных замеров «до/после правки описаний» с таблицами успешных вызовов в посте нет. OAuth и безопасность MCP автор не разбирает — это изолированное пошаговое руководство про тексты описаний. В конце упоминаются Vinkius и Vinkius MCP Catalog как контекст инструментов продакшн-уровня; конкретных имён сторонних MCP-серверов (npm-пакеты, репозитории) материал не приводит.

Источники

Renato Marinho, «Stop writing MCP tool descriptions like a human is reading them» — Dev.to, опубликовано 3 августа 2026 г.