Tool Schema Design в 2026: как проектировать инструменты, чтобы агент не фантазировал

Короткая версия

Хорошая tool schema в 2026 обычно делает пять вещей:

1. Чётко отделяет один action от другого
2. Минимизирует свободный текст в аргументах
3. Фиксирует обязательные поля и enums
4. Разводит propose и commit для risky actions
5. Даёт приложению удобную post-validation

Что особенно помогает

• маленькие инструменты вместо mega-tool;
• понятные названия полей;
• required почти для всех значимых аргументов;
• enums вместо vague strings;
• отдельный idempotency_key или dry_run, если у действия есть side effects.

Нужно, чтобы агент мог вернуть деньги клиенту. Что лучше: один tool `billing_action` со свободным `payload` или отдельный `issue_refund` со строгими полями?

1. Схема инструмента - это decision boundary

Когда модель выбирает tool, она отвечает сразу на два вопроса:

• какое действие вообще допустимо;
• какие аргументы нужны для него.

Поэтому схема инструмента влияет не только на format correctness, но и на поведение всей системы:

• сколько будет ложных вызовов;
• как часто модель выберет не тот tool;
• можно ли валидировать action до side effect;
• насколько удобно строить human review и audit trail.

Если schema не задаёт явную границу между safe read и dangerous write, агент начинает относиться к ним как к одной операции.

2. Один tool = один глагол

Самое полезное practical правило: инструмент должен выражать один чёткий глагол.

Хорошие примеры:

• search_kb
• lookup_order
• draft_email
• issue_refund
• create_ticket

Слабые примеры:

• process_request
• manage_customer
• handle_task
• run_workflow

Почему это критично:

• проще выбрать правильный tool;
• проще оценивать false positives;
• легче задавать approval policy;
• легче разделять read path и write path.

3. Ограничивайте пространство аргументов

Модель лучше работает там, где ей не нужно каждый раз изобретать допустимые значения.

Поэтому production schema обычно выигрывает от:

• enum для типов действий и категорий;
• явных required полей;
• коротких и стабильных идентификаторов;
• отдельных boolean flags только там, где они реально нужны;
• чисел и дат в machine-friendly формате.

Частая проблема - поле вида:

{ "priority": "something urgent but maybe medium" }

Для модели это invitation to improvise. Гораздо лучше:

{ "priority": "high" }

с жёстким enum low | medium | high.

4. Free text должен быть вспомогательным, а не управляющим

Свободный текст полезен для:

• человеческих заметок;
• search query;
• drafted message;
• justification.

Но free text плохо подходит как основа для управления side effects. Если действие реально зависит от текста вроде mode, action_notes, special handling, вы переносите decision boundary из schema обратно в prose.

Это обычно ломает:

• deterministic validation;
• policy checks;
• routing;
• regression evals.

5. Разделяйте read, propose и commit

Это один из самых сильных паттернов для tool design.

Read

Инструменты, которые только читают:

• lookup;
• search;
• retrieve;
• inspect.

Propose

Инструменты, которые готовят действие, но ещё ничего не меняют:

• draft update;
• build refund proposal;
• prepare message;
• assemble SQL preview.

Commit

Инструменты, которые уже меняют внешний мир:

• send email;
• update record;
• charge card;
• delete file.

Если risky workflow оформить именно так, появляется понятная граница для:

• approval;
• idempotency;
• auditing;
• retries.

6. Не заставляйте модель заполнять скрытые инварианты

Есть поля, которые модель не должна придумывать сама:

• customer_id, если он должен идти из trusted system;
• currency, если она уже задана ордером;
• actor_id, если это identity текущего пользователя;
• policy_version, если его задаёт приложение.

Такие значения лучше подставлять app-side. Иначе агент начинает:

• копировать их из контекста с ошибками;
• изобретать отсутствующие значения;
• смешивать user input и system state.

Общее правило: всё, что можно безопасно определить кодом, лучше не поручать модели.

7. Что особенно ломает tool use

Mega-tool

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

Optional overload

Когда почти все поля optional, модель начинает гадать, что реально обязательно.

Скрытые side effects

Название выглядит безопасно, а внутри уже происходит write.

Argument aliasing

Похожие поля вроде customer, customer_id, customer_ref, account создают путаницу и bad calls.

Смешение user-facing и machine-facing полей

Например, когда один и тот же notes должен и объяснять решение человеку, и управлять логикой backend.

8. Какие метрики полезны именно для schema design

Если смотреть только на общий task success, вы не поймёте, в чём проблема. Полезнее отдельные tool metrics:

• wrong-tool rate;
• missing-required-args rate;
• schema validation failure rate;
• human-edit-before-approve rate;
• dangerous-call false positive rate;
• retry-after-validation rate.

Именно эти метрики быстрее показывают, что схема перегружена или двусмысленна.

Пример safe tool schema

{
  "name": "issue_refund",
  "description": "Issue a refund for an already validated order. Use only after order lookup and policy checks pass.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string" },
      "amount": { "type": "number" },
      "currency": { "type": "string", "enum": ["USD", "EUR", "KZT"] },
      "reason": {
        "type": "string",
        "enum": ["duplicate_charge", "service_failure", "fraud", "goodwill"]
      },
      "idempotency_key": { "type": "string" },
      "requires_approval": { "type": "boolean" }
    },
    "required": ["order_id", "amount", "currency", "reason", "idempotency_key", "requires_approval"]
  }
}

Практический checklist

1. Один tool = один глагол
2. Все risky writes отделены от reads
3. Почти все важные поля required
4. Enums используются там, где possible
5. Trusted values подставляются кодом, а не моделью
6. Есть idempotency, approval и post-validation для side effects

Практический совет: если tool сложнее объяснить одной фразой и одним примером вызова, почти всегда стоит разбить его на два или три инструмента с более узкой обязанностью.