Дизайн кастомного инструмента для агента

Спроектируй инструмент для агента. Назначение: {{purpose}}.

1. Решение: новый инструмент или нет?

Не создавай новый если:

• Можно решить через комбинацию существующих
• Используется реже 1 раза в N задач
• Слишком общий ("doStuff(args)")

Создавай если:

• Часто нужен в этом домене
• Без него агент делает много неэффективных шагов
• Естественная атомарная операция

2. Имя

Глагол + объект, snake_case или camelCase консистентно:

search_documents      ✓
list_users            ✓
create_invoice        ✓

doStuff               ✗
helper                ✗
process               ✗

Имя должно быть самоочевидным — модель не должна читать description чтобы понять что это.

3. Описание

Это самая важная часть — модель решает вызвать инструмент по описанию.

name: search_documents
description: |
  Search the knowledge base for documents matching a query.
  Returns up to 10 most relevant documents with title, excerpt, and URL.
  Use when the user asks about company-specific information not in your training data.

  DO NOT use for general knowledge questions — answer those directly.
  DO NOT use for personal info — use get_user_profile instead.

Структура описания

• Что делает (одно предложение)
• Что возвращает
• Когда использовать
• Когда не использовать (анти-кейсы)

4. Параметры

Минимум обязательных, разумные defaults для остальных:

input_schema:
  type: object
  required: [query]
  properties:
    query:
      type: string
      description: "The search query. Use natural language, not keywords."

    limit:
      type: integer
      description: "Max results to return. Default 10, max 50."
      default: 10
      maximum: 50

    filters:
      type: object
      description: "Optional filters: { source: 'docs' | 'wiki', updated_after: ISO-date }"

Описывай параметры так, чтобы модель не угадывала

• Формат значений (date format, regex, enum)
• Какие значения допустимы / нет
• Что значит default

5. Возвращаемое значение

Структурированно, документировано:

output_schema:
  type: object
  properties:
    results:
      type: array
      items:
        type: object
        properties:
          id: { type: string }
          title: { type: string }
          excerpt: { type: string, description: "First 200 chars" }
          url: { type: string }
          score: { type: number, description: "0-1, higher is more relevant" }
    total: { type: integer }
    truncated: { type: boolean }

6. Ошибки

Не throw — возвращай структурированную ошибку:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Try again in 60s.",
    "retry_after": 60
  }
}

Модель прочитает и решит что делать.

Коды ошибок

• invalid_input — параметры не валидны
• not_found — то что просили не найдено
• permission_denied — нет прав
• rate_limit_exceeded — превышен лимит
• internal_error — что-то сломалось

7. Идемпотентность и безопасность

• Read-only? Без проблем
• Write? Идемпотентен? Если нет — поддержи idempotency_key параметр
• Destructive? Двухшаговое подтверждение (dry_run: true опция)

8. Документация для людей

Помимо JSON Schema — человеко-понятная страница:

• Примеры вызовов (с реальными данными)
• Edge cases
• Стоимость / rate limits
• Что произойдёт если не сработало

9. Тестирование

Перед раскатом — тесты:

• Тест с правильными параметрами → нормальный результат
• Тест с невалидными параметрами → нормальная ошибка (не 500)
• Тест с edge inputs (пустая строка, очень большое число)
• Тест от агента: "У меня нет такого инструмента, что делать?" → не должен пытаться вызвать

Анти-паттерны

• ❌ exec(cmd) — даёт агенту слишком много власти, угроза безопасности
• ❌ query(sql) — то же самое
• ❌ Параметры без описания — модель будет угадывать
• ❌ Описание длиннее 300 слов — модель потеряется
• ❌ Один инструмент с 20 параметрами — разбей на специализированные