Как описать инструмент модели

Модель не видит ваш код — она видит только описание инструмента. От качества этого описания зависит, верно ли агент его вызовет.

Описание инструмента — структурированная карточка (имя, описание на естественном языке, схема параметров), по которой LLM понимает, что инструмент делает и как его вызвать.

Три части описания

• Имя — короткий идентификатор, например get_weather. Модель указывает его, когда хочет вызвать инструмент.
• Описание — фраза на естественном языке: что делает инструмент и когда его применять. Это самая важная часть: по ней модель решает, брать инструмент или нет.
• Схема параметров — какие аргументы нужны, их типы и какие обязательны. Обычно в формате JSON Schema.

Пример схемы

Так выглядит типичное описание инструмента, которое отдают модели (формат function calling). Это просто данные — соберём их в Python и выведем как JSON.

import json

tool = {
    "name": "get_weather",
    "description": "Возвращает текущую погоду в указанном городе. "
                   "Используй, когда пользователь спрашивает про погоду.",
    "parameters": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "Название города"},
            "units": {"type": "string", "enum": ["c", "f"],
                      "description": "Единицы температуры"},
        },
        "required": ["city"],
    },
}

print(json.dumps(tool, ensure_ascii=False, indent=2))
print("---")
print("Имя:", tool["name"])
print("Обязательные параметры:", tool["parameters"]["required"])

Вывод:

{
  "name": "get_weather",
  "description": "Возвращает текущую погоду в указанном городе. Используй, когда пользователь спрашивает про погоду.",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "Название города"
      },
      "units": {
        "type": "string",
        "enum": [
          "c",
          "f"
        ],
        "description": "Единицы температуры"
      }
    },
    "required": [
      "city"
    ]
  }
}
---
Имя: get_weather
Обязательные параметры: ['city']

Как выглядит вызов в API

В настоящем function calling вы передаёте список таких описаний модели, а она в ответ возвращает не текст, а структуру «хочу вызвать инструмент X с аргументами Y». Это нельзя запустить в браузере (нужен ключ и сеть), поэтому показываем как текст.

// что вернёт модель (упрощённо):
{
  "tool_call": {
    "name": "get_weather",
    "arguments": { "city": "Москва", "units": "c" }
  }
}
// ваш код выполняет get_weather("Москва", "c") и
// возвращает результат модели следующим сообщением

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

• Понятное «когда применять» — модель чаще ошибается с выбором инструмента, чем с аргументами. Опишите границы: «используй для X, не используй для Y».
• Говорящие имена параметров — city лучше, чем p1.
• Перечисления (enum) там, где значений мало, — это снижает число ошибок.
• Минимум обязательных параметров — чем меньше модель должна угадать, тем надёжнее вызов.

Частые ошибки

• Слишком общее описание («работает с данными») — модель не понимает, когда брать инструмент.
• Два инструмента с похожими описаниями — модель путает их.
• Сложная вложенная схема — модель чаще ошибается в аргументах.

Итог

• Модель видит инструмент только через описание: имя + текст «что и когда» + схема параметров.
• Текст описания важнее всего: по нему модель решает, применять ли инструмент.
• Делайте описания однозначными, имена говорящими, схему простой, обязательных параметров — минимум.