Your agent has 80 functions for orders, inventory, email, and more. Each function carries a parameter schema. If you send every full schema with every request, context grows before the user asks a question. Google launched Tool Retrieval in preview for the Gemini Interactions API on November 19: the model sees a deferred tool's name and description, then loads its detailed schema only when needed. Before switching it on, measure the size of your own catalog.
A local measurement with clear limits
This experiment creates 80 synthetic functions of similar size. It compares two JSON representations: all schemas loaded versus five full schemas and 75 entries with only type, name, and description. That approximates the data-size question behind catalog design. It does not count Gemini tokens, measure latency, or predict a bill. The API may serialize tools differently internally.
The practical decision is whether your schemas are large enough to justify a Tool Retrieval trial. If descriptions account for most of the payload, deferring parameters may help little. If the payload shrinks substantially, compare real requests with and without deferral once you have API access.
Reproducible script
Save this as schema_size.py and run python3 schema_size.py. It needs no key or network access:
import json
def tool(number):
return {
"type": "function",
"name": f"lookup_record_{number:02d}",
"description": f"Look up a permitted business record in category {number:02d}.",
"parameters": {
"type": "object",
"properties": {
"record_id": {"type": "string", "description": "Business record ID"},
"tenant_id": {"type": "string", "description": "Tenant ID"},
"include_history": {"type": "boolean", "description": "Include changes"},
"limit": {"type": "integer", "description": "Maximum rows"},
},
"required": ["record_id", "tenant_id"],
},
}
def size(value):
return len(json.dumps(value, ensure_ascii=False,
separators=(",", ":")).encode())
full = [tool(i) for i in range(80)]
deferred = [
item if i < 5 else {k: v for k, v in item.items()
if k != "parameters"}
for i, item in enumerate(full)
]
a, b = size(full), size(deferred)
print(a, b, a - b, round((1 - b / a) * 100, 1))
assert len(full) == len(deferred) == 80
On my machine, the full synthetic sample occupied 35,441 bytes. Keeping five full schemas and 75 summaries occupied 10,766 bytes: a difference of 24,675 bytes, or 69.6% locally. This is a teaching dataset, not a measurement of your agent. The snippet shown keeps the same schema structures and text as the script I ran. Your own definitions will yield different counts; record their reduction percentage as well.
Use your actual tool catalog
- Export tool definitions to JSON in a development environment. Remove secrets and customer data before saving it.
- Count how often each tool is called over a defined window, such as seven days. Keep the five most common loaded and simulate the rest with names and descriptions.
- Measure both JSON representations with identical serialization. Record tool count, average description length, and reduction percentage.
- In an actual Gemini trial, compare reported input tokens, latency, correct tool selection, and internal searches. Local byte reduction is not a substitute for those results.
Google says to add tool_search and set defer_loading: true on chosen functions. Managed retrieval happens inside one request. Client-side retrieval also exists for catalogs with their own permission filter, but adds a round trip. Google suggests keeping frequent tools loaded. This is a preview feature for Gemini 3.6 and later through the Interactions API. If your agent relies on per-user tool access, enforce authorization on the server even when retrieval finds a tool.
When to ship it
A promising result would be fewer input tokens and acceptable latency without worse tool selection across representative tasks. A negative result would be wrong tool choices or more searches than expected, even if the initial payload shrinks. I did not run the Gemini API or measure billing in an account for this article; the local byte comparison is the only test I performed. The next step is an account-level comparison across 20 real tasks with human review and a spending cap.
