La descripción decide qué herramienta elige el modelo

Cuando un agente tiene get_customer y lookup_order, el modelo no “sabe” cuál usar: lo decide leyendo lo que dice cada una. La descripción de la herramienta (tool description) es lo principal que usa para elegir. Si dice “Retrieves order details” y nada más, la elección entre herramientas parecidas se vuelve una moneda al aire.

Las cinco partes de una buena descripción

1. Propósito: qué hace y qué devuelve.
2. Entradas esperadas: formato de cada parámetro, por ejemplo order_id con la forma #12345.
3. Ejemplos de consultas: “¿dónde está mi pedido #12345?”, “¿cuándo llega lo que compré ayer?”.
4. Casos límite (edge cases): un número de seguimiento del correo parece un ID, pero no lo es y va a track_shipment.
5. Límites explícitos (explicit boundaries) frente a las vecinas: “para preguntas sobre el perfil del cliente, usá get_customer”.

Los límites tienen que ser recíprocos: si lookup_order manda las preguntas de perfil a get_customer, pero get_customer no dice dónde termina, sigue pareciendo válida para pedidos.

Tipos de datos, códigos de error o rate limits son especificación de la API: sirven para integrar, no para elegir.

Cuándo no alcanza con la descripción

Síntoma	Arreglo
Herramienta de un solo propósito con descripción pobre	Ampliar la descripción
Dos nombres casi iguales (analyze_content y analyze_web_content)	Renombrar el genérico, por ejemplo a extract_web_results
Una herramienta hace varias cosas (un parámetro action, “analiza y resume”)	Dividirla en herramientas con un solo propósito
Una sola consulta partida en cuatro get_order_*	Unificarlas: se divide por responsabilidad, no por campo
Una herramienta nueva “devuelve todo” y rompe a las demás	Acotarla a lo que solo ella aporta

Una herramienta con un solo propósito (purpose-specific tool) tiene su propio contrato de entrada y salida: analyze_document se convierte en extract_data_points, summarize_content y verify_claim_against_source. Cuando la superposición funcional (functional overlap) está en el nombre, conviene sacarla de raíz en lugar de compensarla con una descripción más larga que pelea contra el nombre.

El system prompt también elige

El modelo elige con todo el contexto: system prompt, descripciones y mensaje. Una instrucción como “Always check customer details before proceeding” asocia cada pedido con get_customer, y puede ganarles en silencio a descripciones bien escritas. Si el error sigue después de mejorar las descripciones, o aparece solo cuando el mensaje tiene cierta palabra (“account”), buscá una instrucción del system prompt que compita. Si expresa un requisito real, reescribila con su alcance exacto (“verificá antes de cambiar datos”, no “antes de cualquier cosa”) en lugar de borrarla.

Las trampas típicas

Como primer paso, todas tratan el síntoma o son sobreingeniería:

• sumar ejemplos (few-shot) de elección de herramientas: cuestan tokens en cada pedido y la ambigüedad sigue;
• un router por palabras clave o un clasificador previo;
• forzar tool_choice;
• unificar todo en una herramienta genérica con un parámetro type, que solo mueve la ambigüedad al parámetro.

En el examen

Si las descripciones son de una línea, el primer paso proporcionado es reescribirlas con las cinco partes. Si ya están bien, mirá el nombre, si la herramienta hace varias cosas y el system prompt, en ese orden.