Descripciones de herramientas: cómo lograr que Claude elija la herramienta correcta

Hola, soy Nolan, de EvoAcademy, y bienvenidos y bienvenidas a la cápsula uno del Módulo dos. Un aviso: lo que escuchas es mi voz, pero este audio fue generado con inteligencia artificial, bajo la supervisión del equipo de EvoAcademy. Además tenemos una comunidad abierta, en evoacademy.cl/comunidad.

Hoy vemos el task statement dos punto uno: diseñar herramientas con descripciones y límites claros. Una herramienta es una función que el modelo puede pedir que se ejecute, como consultar un vuelo.

El modelo no ve tu código. Para decidir qué herramienta llamar solo tiene el nombre, el campo description y el campo input schema, que define qué datos recibe la herramienta. Por eso la guía oficial dice que la descripción es el mecanismo principal de selección. Con descripciones mínimas y parecidas, el modelo no tiene con qué distinguirlas, y la selección se vuelve poco confiable.

La guía pide que cada descripción incluya cuatro cosas: los formatos de entrada que acepta, consultas de ejemplo, casos borde, que son situaciones poco habituales, y límites que expliquen cuándo usarla y cuándo usar otra herramienta parecida. Los límites son lo que más se olvida: una buena descripción también dice qué no hace y adónde ir en ese caso. La documentación de Anthropic recomienda al menos tres o cuatro oraciones por descripción, y ofrece el campo opcional input examples para mostrar entradas válidas.

Después de mejorar la descripción, la guía da tres técnicas más. Si dos herramientas se superponen en nombre y descripción, entonces el modelo las confunde, y corresponde renombrar y reescribir hasta eliminar la superposición. Por su parte, si una herramienta es genérica y su salida cambia cada vez, entonces conviene dividirla en herramientas con un contrato claro, que dice qué recibe y qué devuelve cada una. Además, si las descripciones ya están bien y el error sigue, entonces se revisa el system prompt, que es el conjunto de instrucciones fijas que recibe el modelo. Una instrucción atada a una palabra clave puede pasar por encima de una buena descripción.

Una pregunta. Una clínica veterinaria tiene un agente con esta instrucción en el system prompt: si el dueño menciona la palabra vacuna, agenda una cita. Un dueño pregunta qué vacunas necesita su cachorro, y el agente le agenda una hora. Las descripciones están bien escritas. ¿Qué revisarías primero?

El system prompt. El modelo asoció la palabra vacuna con agendar, y esa instrucción le ganó a la descripción. La corrección es pedir que agende solo cuando el dueño solicite una hora de forma explícita.

Ahora, dos preguntas de práctica. Pregunta uno. Una aerolínea usa un agente de atención a pasajeros con dos herramientas: get flight, descrita como obtiene datos de un vuelo, y get baggage, descrita como obtiene datos de equipaje. Las dos aceptan códigos de seis caracteres. Cuando un pasajero pregunta dónde está su maleta y da la etiqueta B X cuatro ocho dos uno, el agente suele llamar a get flight. ¿Cuál es el primer paso más efectivo? Opción A: crear un servicio previo que clasifique cada mensaje y habilite solo una herramienta. Opción B: reescribir ambas descripciones con el formato de código que acepta cada una, una consulta de ejemplo y cuándo usar la otra. Opción C: agregar al system prompt que elija con mucho cuidado entre las dos. Opción D: unir las dos en una sola herramienta.

La correcta es B. El modelo no puede distinguir dos herramientas con descripciones mínimas, y B ataca esa causa con poco esfuerzo. La A es sobreingeniería. La C no aporta información nueva. La D puede ser válida, pero cuesta más para un primer paso.

Pregunta dos, de respuesta múltiple. Elige dos. Una aseguradora tiene un agente de siniestros con dos búsquedas, search policy text y search policy docs, de descripciones casi idénticas. Además tiene handle claim, una herramienta genérica que registra siniestros, estima daños o verifica cobertura, con una salida distinta cada vez. Opción A: renombrar search policy docs con un nombre específico y reescribir su descripción. Opción B: dividir handle claim en herramientas de un solo propósito, cada una con su contrato de entrada y de salida. Opción C: escribir en el system prompt, en mayúsculas, que nunca use search policy text para documentos. Opción D: construir una capa que elija por palabras clave. Opción E: fusionar todo en una herramienta llamada claims. ¿Cuáles dos?

Las correctas son A y B, las dos técnicas de la guía: renombrar y reescribir para eliminar la superposición, y dividir la herramienta genérica. La C compensa en el prompt una ambigüedad que vive en la herramienta. La D agrega una capa que no ataca la causa. La E crea una herramienta aún más genérica.

Resumen: la descripción decide qué herramienta se llama. Si hay confusión, primero mejora descripciones, renombra y divide, y al final revisa el system prompt. Si te sirvió, sigue el podcast, dale cinco estrellas y activa las notificaciones. En la próxima cápsula vemos los errores estructurados en herramientas MCP: por qué un mensaje genérico de falla no dice si reintentar o escalar. Nos escuchamos en la próxima cápsula de EvoAcademy.