Búsqueda de herramientas: herramientas dinámicas
En esta página
- Búsqueda de herramientas: herramientas dinámicas
- El problema de los catálogos de herramientas extensos
- Activación de la búsqueda de herramientas
- Organización del catálogo de funciones
- Buenas prácticas para las descripciones
- Combinación de la búsqueda de herramientas con herramientas fijas
- Patrón: sistema multidominio
- Puntos clave
Lección actualizada el 2 de noviembre de 2026 según la documentación de OpenAI: la herramienta Code Interpreter requiere ahora un parámetro
container(añadido a todos los ejemplos), las partes de texto de entrada tienen el tipoinput_text, y la búsqueda web utiliza la herramientaweb_search(web_search_previewes ahora una herramienta heredada sin filtros de dominio). Los archivos generados se recuperan mediante las funcionesfichiers_generesytelechargerde la Lección 10. Fuentes: Code Interpreter · Búsqueda web.
Búsqueda de herramientas: herramientas dinámicas
Cuando dispones de decenas o cientos de funciones, declararlas todas en cada llamada resulta contraproducente: el modelo pierde precisión y los costes se disparan. La búsqueda de herramientas (Tool Search) resuelve este problema permitiendo que el modelo consulte la herramienta adecuada en un catálogo indexado.
El problema de los catálogos de herramientas extensos
El coste de un catálogo de herramientas grande es invisible de dos formas. En primer lugar, económicamente: la definición de cada función se envía con cada solicitud, incluidas las noventa y ocho que no se utilizarán. A gran escala, esto acaba superando el coste de las propias respuestas. En segundo lugar, y lo que es más grave, cualitativamente: más allá de unas pocas docenas de herramientas con ámbitos solapados, el modelo toma decisiones peores. Demasiadas opciones degradan la toma de decisiones, aquí como en cualquier otro contexto.
# 5 funciones = ~500 tokens de contexto
# 50 funciones = ~5000 tokens de contexto
# 200 funciones = imposible de gestionar eficientemente
# El modelo pierde precisión cuando hay demasiadas funciones
# A veces elige la función incorrecta o alucina parámetros
Activación de la búsqueda de herramientas
La búsqueda de herramientas invierte la lógica: en lugar de presentarlo todo al modelo, indexas el catálogo y le muestras únicamente lo que coincide con la solicitud actual. El mecanismo se basa en la búsqueda semántica sobre las descripciones; por eso la siguiente sección no es solo un consejo de estilo, sino un requisito para que el sistema funcione.
from openai import OpenAI
client = OpenAI()
# Declarar un gran número de funciones
all_functions = [
{
"type": "function",
"name": "create_invoice",
"description": "Create a new invoice for a customer",
"parameters": {"type": "object", "properties": {"client_id": {"type": "string"}}, "required": ["client_id"]}
},
{
"type": "function",
"name": "cancel_invoice",
"description": "Cancel an existing invoice",
"parameters": {"type": "object", "properties": {"invoice_id": {"type": "string"}}, "required": ["invoice_id"]}
},
# ... docenas de otras funciones
]
# Usar la búsqueda de herramientas para que el modelo encuentre la función correcta
response = client.responses.create(
model="gpt-5.6-terra",
input="Cancel invoice FAC-2026-0042",
tools=[{
"type": "tool_search",
"tool_search": {
"tools": all_functions
}
}]
)
El modelo recibe en su contexto únicamente las funciones relevantes para la solicitud, no el catálogo completo.
Organización del catálogo de funciones
Dos principios bastan para estructurar un catálogo que siga siendo navegable. Prefija los nombres por dominio (crm_, billing_, inventory_): la lectura del rastro de ejecución se vuelve inmediata y desaparecen los conflictos de nombres. Además, asigna a cada función un ámbito claro: dos funciones cuyas descripciones se solapen producirán elecciones inestables, tanto si quien realiza la llamada es un humano como un motor vectorial.
crm_catalog = [
{
"type": "function",
"name": "crm_search_customer",
"description": "Search for a customer in the CRM by name, email, or ID. "
"Use to find information about an existing customer.",
"parameters": {
"type": "object",
"properties": {
"term": {"type": "string", "description": "Search term"},
"field": {"type": "string", "enum": ["name", "email", "id"]}
},
"required": ["term"],
"additionalProperties": False
},
"strict": True
},
{
"type": "function",
"name": "crm_create_customer",
"description": "Create a new customer in the CRM. "
"Use when a customer does not yet exist.",
"parameters": {
"type": "object",
"properties": {
"name": {"type": "string"},
"email": {"type": "string"},
"company": {"type": "string"}
},
"required": ["name", "email", "company"],
"additionalProperties": False
},
"strict": True
}
]
billing_catalog = [
{
"type": "function",
"name": "bill_create_invoice",
"description": "Create an invoice. Requires an existing customer.",
"parameters": {
"type": "object",
"properties": {
"client_id": {"type": "string"},
"lines": {"type": "array", "items": {"type": "object", "properties": {
"description": {"type": "string"},
"amount": {"type": "number"}
}}}
},
"required": ["client_id", "lines"],
"additionalProperties": False
},
"strict": True
}
]
# Fusionar todos los catálogos
full_catalog = crm_catalog + billing_catalog
Buenas prácticas para las descripciones
Escribe descripciones pensadas para la búsqueda, no para la documentación. «Recuperar datos del cliente» nunca aparecerá en una consulta sobre «historial de pedidos» o «datos de contacto de facturación»: las palabras que tus usuarios escriben realmente deben figurar en el texto indexado. Una descripción útil nombra casos de uso y vocabulario empresarial, no detalles de implementación.
# Malo: demasiado genérico
{"name": "get_data", "description": "Retrieve data"}
# Bueno: específico con contexto de uso
{
"name": "hr_check_leave_balance",
"description": "Check an employee's leave balance (vacation, personal time, sick leave). "
"Returns remaining days by leave type. "
"Use when an employee asks how many days they have left."
}
# Bueno: con sinónimos para mejorar la búsqueda
{
"name": "acct_reconcile_bank",
"description": "Bank reconciliation: compare accounting entries "
"with bank transactions. Account reconciliation. "
"Use to verify consistency between accounting records "
"and bank statements."
}
Combinación de la búsqueda de herramientas con herramientas fijas
La mezcla es el modo de operación estándar en producción. Unas pocas herramientas transversales —hora, usuario actual, búsqueda de documentos— permanecen declaradas de forma permanente porque sirven para casi todas las solicitudes, mientras que el catálogo de negocio se mantiene dinámico. Esto mantiene el contexto ligero sin obligar al modelo a buscar lo que necesita en cada ocasión.
response = client.responses.create(
model="gpt-5.6-terra",
input="Search the web for this month's sales and create the corresponding invoice",
tools=[
# Herramientas siempre disponibles
{"type": "web_search"},
{"type": "code_interpreter", "container": {"type": "auto"}},
# Catálogo dinámico
{
"type": "tool_search",
"tool_search": {
"tools": full_catalog # más de 200 funciones
}
}
]
)
Patrón: sistema multidominio
class MultiDomainSystem:
def __init__(self):
self.client = OpenAI()
self.catalogs = {}
def register_domain(self, name: str, functions: list[dict]):
"""Registrar un catálogo de funciones para un dominio."""
self.catalogs[name] = functions
def full_catalog(self) -> list[dict]:
"""Fusionar todos los catálogos."""
result = []
for functions in self.catalogs.values():
result.extend(functions)
return result
def execute(self, query: str) -> str:
"""Ejecutar una consulta con búsqueda de herramientas en todos los dominios."""
response = self.client.responses.create(
model="gpt-5.6-terra",
input=query,
tools=[{
"type": "tool_search",
"tool_search": {
"tools": self.full_catalog()
}
}]
)
# Procesar llamadas a funciones
for item in response.output:
if item.type == "function_call":
result = self.dispatcher(item.name, item.arguments)
# ... bucle de llamada a funciones
return response.output_text
def dispatcher(self, name: str, arguments: str):
"""Enrutar la llamada al servicio correcto."""
# Tu lógica de enrutamiento
pass
# Uso
system = MultiDomainSystem()
system.register_domain("crm", crm_catalog)
system.register_domain("billing", billing_catalog)
system.register_domain("hr", hr_catalog)
system.register_domain("support", support_catalog)
# El modelo encuentra automáticamente la función correcta
# entre cientos de posibilidades
result = system.execute("How many vacation days does Marie Dupont have left?")
Puntos clave
- La búsqueda de herramientas resuelve el problema de los catálogos de funciones extensos
- El modelo recibe en su contexto únicamente las funciones relevantes
- Las descripciones ricas y específicas son esenciales para la precisión
- Prefija los nombres de las funciones por dominio para mejorar la legibilidad
- Combina la búsqueda de herramientas con herramientas integradas siempre disponibles