Проектирование интерфейсов инструментов с чёткими описаниями и границами

Суть

Описание инструмента — единственный механизм, по которому модель выбирает, что вызвать. Скудные или пересекающиеся описания делают выбор между похожими инструментами ненадёжным.

Анатомия хорошего описания

Полное описание содержит пять частей: когда использовать, когда НЕ использовать, формат входа, структура выхода, краевые случаи. Имя инструмента тоже несёт смысл: расплывчатое имя подрывает даже идеальное описание.

Почему не «общий инструмент с режимом»

Generic-инструмент с параметром-режимом прячет неоднозначность внутрь инструмента — корень проблемы тот же. А инструкции по ключевым словам в system prompt создают непредусмотренные ассоциации и новые коллизии.

Определение инструмента с полным описанием

// Определение инструмента: имя, развёрнутое описание, схема входа.
tool := map[string]any{
	"name": "search_customer_orders",
	"description": "Поиск истории заказов клиента по customer_id или email.\n" +
		"Когда использовать: вопросы о заказах, доставках, покупках.\n" +
		"НЕ использовать для: проверки склада, описаний товаров, возвратов.\n" +
		"Формат входа: customer_id (строка) ИЛИ email (строка).\n" +
		"Возвращает: список заказов с полями order_id, status, total, items[], created_at.\n" +
		"Краевые случаи: пустой список, если заказов нет (это НЕ ошибка).",
	"input_schema": map[string]any{
		"type": "object",
		"properties": map[string]any{
			"customer_id": map[string]any{"type": "string"},
			"email":       map[string]any{"type": "string"},
		},
	},
}

Anti-patterns

Ловушка	Почему не работает	Верный паттерн
Уточнять выбор инструмента инструкцией в промпте	Ключевые слова создают новые коллизии	Переписать описания однозначно; при нужде переименовать
Слить пересекающиеся инструменты в один generic с режимом	Режим переносит неоднозначность внутрь инструмента	Разделить на инструменты под конкретную цель, каждый с одним контрактом
Делать описание коротким — «меньше шума»	Детали снижают неоднозначность; модели нужен сигнал, а не тишина	Включить формат входа/выхода, краевые случаи, негативные примеры
Оставить расплывчатое имя, улучшив только описание	Имя несёт смысл и подрывает описание	Переименовать под область (`analyze_content` → `extract_web_results`)

Exam traps

Ловушка	Почему не работает	Верный паттерн
Полагаться на system prompt для ясности маршрутизации	Инструкции вероятностны; пересечения ключевых слов рождают коллизии	Описания должны быть однозначны на уровне описания
Считать, что длинные имена спасают от путаницы	Имя — лишь часть сигнала; решает пересечение описаний	Чёткие описания с границами устраняют неоднозначность

Практическое задание (T1)

Создать набор из 4 инструментов поддержки: search_orders, process_refund, check_shipping_status, escalate_to_human.
В каждом описании дать: когда использовать, когда нет, формат входа, структуру выхода, краевые случаи.
Написать system prompt с инструкцией по ключевому слову, вызывающей коллизию, — затем исправить.
Дать 3 неоднозначных запроса (напр. «где мои вещи») и проверить детерминированную маршрутизацию.
Найти инструмент, делающий два дела, разделить его и доказать рост точности маршрутизации.

Проверка знаний

Агент поддержки клиентов

Два инструмента: analyze_content (описание «Анализирует контент») и analyze_document (описание «Анализирует документы и контент»). При тестах запросы про PDF-заказы в 40% случаев уходят в analyze_content. Лучшее решение?

A Добавить в system prompt: «всегда использовать analyze_document для PDF»
B Переименовать analyze_content в extract_web_results, переписать описание под ответы web-API, явно указать «не для PDF/загрузок»
C Слить в один analyze с параметром-режимом
D Поднять temperature, чтобы снизить смещение маршрутизации

Многоагентная исследовательская система

Один инструмент analyze_document с режимом (extract_data, summarize, verify_claim). 30% запросов на извлечение запускают суммаризацию. Какая реструктуризация решит это без смены логики?

A Детальнее описать параметры — когда какой режим применять
B В system prompt сопоставить ключевые слова намерения значениям режима
C Разделить на три инструмента — extract_data_points, summarize_content, verify_claim_against_source — каждый с однозначным описанием
D Форсировать tool_choice: {"type":"tool","name":"analyze_document"} и дать модели выбрать режим

Агент поддержки клиентов

System prompt: «когда спрашивают про заказы — приоритет инструменту заказов». Инструменты: search_orders, process_refund (упоминает «возвраты заказов»), lookup_invoice (упоминает «счета по заказам»). Запрос «нужен счёт по заказу для налоговой» уходит в search_orders. Главная причина?

A Модель игнорирует инструкции system prompt
B У search_orders выше вес приоритета, чем у lookup_invoice
C Ключевое слово «заказ» в system prompt создаёт непредусмотренную ассоциацию с search_orders, перебивая более точное совпадение
D Описание lookup_invoice нужно поставить раньше search_orders в списке