Что такое Tool Retrieval и какую проблему он решает
Tool Retrieval - превью-функция Gemini API, которая работает в Interactions API. Агент держит библиотеку инструментов «на подхвате»: в контекст каждого запроса попадают имена и описания функций, а полные схемы параметров API подгружает только под текущую задачу. На стороне кода это выглядит скромно: один элемент в списке инструментов плюс флаг у функций, которые вы готовы отложить.
Проблема, которую решает функция, видна на масштабе. Пока инструментов пять, полные схемы в каждом запросе никого не смущают. Когда их пятьдесят или сто, каждая схема едет в каждом сообщении, и Google перечисляет три следствия: раздувание входных токенов, рост задержки и падение точности выбора инструмента по мере роста списка кандидатов.
Ключевая деталь механики: модель видит имя и описание каждого отложенного инструмента, схемы параметров остаются вне контекста. Когда инструмент нужен, модель запрашивает его по имени, API подгружает полную схему, и вызов функции происходит в рамках того же запроса. Отдельного шага, который разработчик должен вручную оркестрировать между двумя обращениями к модели, нет.
Статус - превью, а не общий доступ. Для проекта это значит: контракт API может поменяться, а часть деталей ниже придётся сверять с документацией, а не с пересказом анонса.
Чем это отличается от отправки всех схем сразу
Разница по трём осям.
- Входные токены. При обычном подходе каждая схема параметров едет в каждом запросе. При Tool Retrieval в контексте остаются имя и описание, а схема загружается только для тех инструментов, которые реально понадобились.
- Задержка. Меньше входных токенов - меньше времени на обработку промпта. Но у схемы есть своя цена: если модель запрашивает инструмент, нужен шаг загрузки, и на отдельном запросе это может дать прибавку вместо экономии.
- Точность выбора. Короткий список кандидатов модель различает лучше, чем длинный. Здесь выигрыш появляется именно при большой библиотеке.
Экономия не бесплатная. Описания инструментов остаются в контексте: они и есть тот сигнал, по которому модель понимает, что инструмент существует и когда его звать. Длинные подробные описания съедают часть выигрыша.
Второй ограничитель: эффект растёт с числом инструментов и падает, когда модель в большинстве запросов дёргает почти весь набор. Схемы всё равно загружаются, только теперь ещё и через дополнительный шаг.
Кому это нужно в первую очередь
Сценарии, где подход окупается:
- агент с десятками инструментов, где в одном запросе нужны два-три;
- мультитул-ассистент с разными доменами: биллинг, поддержка, аналитика, работа с файлами;
- подключение удалённых MCP-серверов с широким набором функций;
- внутренняя платформа, где библиотека инструментов растёт быстрее, чем команда успевает чистить список.
Обратный случай: три-пять инструментов, которые вызываются почти в каждом запросе. Откладывать нечего, экономия будет нулевой, а шаг поиска схемы останется.
Прикидка на пальцах: разделите число инструментов, нужных в типичном запросе, на общий размер библиотеки. Чем меньше доля, тем больше схем останется незагруженными.
Как работает отложенная загрузка схем: пошагово
Цикл одного запроса выглядит так:
- В запрос добавляется инструмент
tool_search, а функции, которые вы готовы отложить, получаютdefer_loading: true. - Модель получает имена и описания всех инструментов, включая отложенные. Схем параметров в контексте нет.
- Модель решает, что для задачи нужен конкретный инструмент, и запрашивает его по имени.
- API подгружает полную схему параметров.
- Модель вызывает функцию с аргументами в рамках того же запроса.
Поиск схемы выполняет сервер Google. Строить собственный индекс эмбеддингов, поднимать отдельный retrieval-сервис и синхронизировать его с библиотекой инструментов не нужно. Этим механика отличается от клиентской предварительной фильтрации, где top-N схем отбирается на вашей стороне до вызова модели: такой подход разбирали в материале про tool-prune и клиентский отбор tool-схем, и там же видно, чем он отличается по цене ошибки.
Настройка: tool_search и defer_loading на практике
В анонсе показан минимальный пример на Python: клиент genai.Client(), в список tools добавлен {"type": "tool_search"}, дальше функция issue_refund с флагом defer_loading, описанием «Refund an order to the original payment method.» и двумя обязательными параметрами. Структура запроса в таком виде:
from google import genai
client = genai.Client()
tools = [
{"type": "tool_search"},
{
"type": "function",
"name": "issue_refund",
"description": "Refund an order to the original payment method.",
"defer_loading": True,
"parameters": {
"type": "object",
"properties": {
"order_id": {"type": "string"},
"amount": {"type": "number"},
},
"required": ["order_id", "amount"],
},
},
# остальные отложенные функции
]
В примере анонса помимо issue_refund отложены ещё более 50 функций. Публикация обрывается на этом месте, поэтому точные имена полей, обёртки и порядок аргументов сверяйте с документацией Interactions API перед копированием кода в проект.
Правила выбора простые. Откладывайте инструменты, которые нужны редко и узко. Инструменты, вызываемые почти всегда, оставляйте с полной схемой в контексте: на них экономии нет, а шаг поиска схемы добавится. Если сомневаетесь, начните с одной группы, например с платёжных операций, и сравните расход токенов.
Как писать описания отложенных инструментов
Описание остаётся единственным сигналом, по которому модель решает, запрашивать схему или нет. Оно должно отвечать на вопрос «когда этот инструмент нужен», а не пересказывать реализацию.
Слабый вариант: "Handles refunds." По такой строке непонятно, идёт ли речь о возврате денег клиенту, об отмене подписки или о внутренней сверке.
Рабочий вариант: "Refund an order to the original payment method. Use when a customer asks for money back on a paid order." Здесь есть действие, объект и условие применения.
Дублирующиеся описания ломают выбор сильнее, чем при полной отправке схем: у модели нет запасного сигнала в виде параметров, она видит только текст. Две функции с описанием «работа с заказом» превращаются в лотерею.
Серверный и клиентский режимы
По умолчанию работает серверный режим: поиск схемы выполняет Google, собственный индекс не нужен.
Клиентский режим с execution: client предназначен для случая, когда реестр инструментов живёт у вас и схемы хранятся на вашей стороне. Поиск и подстановка схемы выполняются вашим кодом, поэтому актуальность схем и их соответствие объявленным именам лежит на вас. Контракт режима в доступном фрагменте анонса не раскрыт: формат ответа на запрос инструмента и требования к нему сверяйте с документацией, догадки здесь дорого стоят.
С удалёнными MCP-серверами логика другая: все инструменты сервера загружаются по требованию, и помечать каждую функцию вручную не требуется. Это удобно для серверов с широким набором методов, где в конкретной задаче нужен один-два.
Экономия токенов и тарификация: чего ждать
Отдельной платы за Tool Retrieval в анонсе не заявлено: токены считаются по стандартным ставкам выбранной модели. Экономия возникает за счёт схем, которые так и не были загружены.
Размер экономии определяется паттерном использования, а не самой функцией. Если из сотни инструментов в типичном запросе нужны три, в контекст попадут три схемы вместо ста. Если нужны девяносто, экономия почти исчезнет, а шаг поиска схемы останется.
Раздела с тарификацией в публичном фрагменте анонса нет, поэтому перед бюджетированием проверьте прайс в документации и не переносите чужие замеры на свой набор.
Как измерить на своих данных: возьмите несколько десятков реальных запросов, прогоните их с полными схемами и с отложенной загрузкой, сравните число входных токенов и долю корректных вызовов инструментов. Второй показатель важнее первого: экономия токенов при просевшей точности выбора обойдётся дороже.
Совместимость: модели, prefix caching, MCP
Поддержка заявлена для Gemini 3.6 и более новых моделей, включая линейку Gemini 4. На более старых версиях рассчитывать на функцию не стоит: в анонсе они не упомянуты.
Совместимость с prefix caching заявлена, но конкретные условия и поведение кеша в момент подгрузки схемы в доступном фрагменте не раскрыты. При планировании расходов на кеширование проверьте эти условия в документации. Общий принцип остаётся: стабильный префикс запроса кешируется лучше, а tool_search и описания отложенных инструментов как раз формируют такой префикс.
MCP: инструменты удалённого сервера загружаются по требованию, весь набор сразу в контекст не попадает.
Статус превью означает, что имена полей, поведение и лимиты могут измениться. Для продакшена закладывайте запас: держите конфигурацию инструментов в одном месте, чтобы правка после изменения API была в одном файле, и не привязывайте бизнес-логику к конкретному формату шагов.
Отладка по шагам interaction.steps
interaction.steps показывает, что происходило внутри одного взаимодействия: какие инструменты модель запрашивала, когда подгружалась схема и с какими аргументами прошёл вызов. Точные названия шагов и полей сверяйте с документацией: в доступном фрагменте анонса их нет, а выдуманные имена полей в отладке только мешают.
По шагам различаются три сценария отказа.
- Модель не запросила нужный инструмент. Проблема в описании: оно не отвечает на вопрос «когда звать» или дублирует описание соседней функции.
- Модель запросила инструмент, но схема не подгрузилась. Проверяйте конфигурацию: наличие
tool_searchв запросе и флагdefer_loadingименно у этой функции. - Схема подгрузилась, но вызов пришёл с неверными аргументами. Проблема в самой схеме параметров: типы, обязательные поля, границы значений. Как JSON Schema превращается в вызов функции, разбирали в материале про единый API tool use в Transformers.
Порядок проверки от дешёвого к дорогому: сначала tool_search в запросе, затем defer_loading у нужного инструмента, затем текст описания, затем схему параметров. Если в шагах видно, что модель просит инструмент по имени, которого нет в библиотеке, ищите расхождение между объявленным именем и тем, что вы ждёте в коде.
Ограничения и подводные камни
- Превью-статус. API может меняться, гарантий стабильности для продакшена нет.
- Ограничение по моделям: Gemini 3.6 и новее.
- Описания инструментов остаются в контексте и занимают токены. Полностью бесплатной библиотеки не бывает.
- Дополнительный шаг поиска схемы может добавить задержку в отдельном запросе, даже если суммарно токенов стало меньше.
- Выигрыш зависит от паттерна вызовов. Агент, который дёргает почти весь набор инструментов, получит мало.
- Требования к описаниям выше, чем при полной отправке схем: у модели нет запасного сигнала в параметрах.
- Часть деталей (клиентский режим, MCP, prefix caching, формат
interaction.steps) в публичном фрагменте анонса не раскрыта. Их нужно сверять с документацией, а не достраивать по аналогии.
Стоит ли включать Tool Retrieval в вашем проекте
Чек-лист для решения:
- Размер библиотеки. Меньше десяти инструментов - повод отложить внедрение. Десятки и сотни - повод посчитать.
- Доля инструментов в типичном запросе. Чем она ниже, тем больше смысла в отложенной загрузке.
- Разнородность доменов. Биллинг, поддержка и аналитика в одном агенте дают разброс, при котором модель редко трогает всё сразу.
- Готовность к превью. Если проект требует стабильного контракта API, закладывайте время на миграцию.
- Качество описаний. Если они писались для людей и звучат как «обработка заказов», сначала придётся их переписать.
Дальше - замер. Прогоните репрезентативную выборку запросов в двух конфигурациях, сравните входные токены и долю корректных вызовов. Похожий порядок оценки нового инструмента, с метриками и проверкой на своих задачах, разбирали в материале про оценку AI-инструмента после запуска.
Итог без рекламного нажима: Tool Retrieval решает конкретную инженерную задачу, раздутый контекст при большой библиотеке инструментов. Если библиотека маленькая или инструменты вызываются почти всегда, включать функцию рано, эффекта не будет. Если инструментов десятки, а в типичном запросе нужны единицы, экономия токенов и более точный выбор инструмента стоят одного эксперимента на реальных запросах.