У определения инструмента две работы, и только одна из них — JSON. Схема говорит, какой формы аргументы; описания говорят, для чего инструмент и что значит каждый аргумент. Схема может быть безупречно корректной и всё же порождать инструмент, который вызывают не вовремя и с правдоподобной чепухой внутри, потому что нигде в JSON не сказано, что есть что. Конструктор пишет схему и проверяет обе половины: структуру и то, описано ли вообще хоть что-нибудь. Строгий режим тоже обработан как надо: он требует перечислить каждое свойство как обязательное и запрещает лишние — и это ловит людей врасплох, потому что в остальном схема выглядит прежней.
Возможности
Параметры с типами, описаниями и необязательными наборами значений
Правило «всё обязательно» строгого режима применяется сразу, а не обнаруживается позже
additionalProperties выставляется верно при включённом строгом режиме
Массивы автоматически получают схему items
Предупреждает о параметре без описания
Ловит повторяющиеся имена параметров
Отмечает перечисление с одним значением — это константа
Выдаёт всё определение, а не только схему
Как использовать Схема инструмента MCP
Назовите инструмент и опишите, когда его применять
Добавьте каждый параметр с типом и описанием
Отметьте обязательные или включите строгий режим
Скопируйте определение в свой массив tools
Пример
Ввод
"strict": true
Результат
Error: strict mode requires every property to be listed as required
В строгом режиме нет необязательных свойств: разрешайте null вместо этого.
Частые ошибки и устранение неполадок
Строгий режим отклонён. — Он требует, чтобы все свойства были обязательными, а additionalProperties равнялось false. Отметьте необязательные как обязательные с разрешённым null или отключите строгий режим.
Инструмент вызывают с неверными аргументами. — Обычно параметры без описаний. По одному имени смысл приходится угадывать, а «id» может быть чем угодно.
Инструмент вызывают не вовремя. — Это описание инструмента, а не схема. Скажите, когда его применять и что он возвращает, а не только что он делает.
Параметр-массив отклонён. — Массивам нужна схема items, говорящая, что внутри. Здесь она добавляется автоматически.
Часто задаваемые вопросы
Что на самом деле меняет строгий режим?
Он гарантирует, что аргументы точно проходят проверку схемой. Цена — каждое свойство должно быть перечислено как обязательное, а лишние не допускаются, поэтому по-настоящему необязательный аргумент придётся описать как обязательный, но допускающий null.
Насколько подробным должно быть описание параметра?
Настолько, чтобы прочитавший только схему понял, что туда класть: формат, единицы, откуда берётся значение. «Адрес электронной почты клиента, на который оформлен заказ» стоит куда больше, чем «почта».
Когда стоит использовать перечисление?
Когда набор допустимых значений действительно замкнут и короток. Это убирает целый класс неверных ответов. Перечисление из одного значения отмечается, потому что это константа, а не параметр.
Это годится и для MCP, и для API?
Схема в обоих случаях — одно и то же подмножество JSON Schema. Обёртка немного отличается, но входная схема — та часть, где легко ошибиться, — идентична.
Каким должно быть хорошее описание инструмента?
Три вещи в двух предложениях: что он делает, когда к нему обращаться и что возвращает. Последнее опускают чаще всего, а пользы от него больше всего: оно говорит, хватит ли одного вызова.