Le diste al agente dos herramientas: updateUser y deactivateUser. Un ticket de soporte dice "cerrar esta cuenta". El agente llamó a deactivateUser. La semana pasada, un ticket casi idéntico hizo que llamara a updateUser con status: "closed", lo cual tu API aceptó y que significaba algo ligeramente diferente en el sistema.
Nada se rompió. El modelo estaba eligiendo entre dos opciones plausibles con descripciones que no le indicaban cuál aplicar. La selección de herramientas es el modo de fallo que la gente atribuye al modelo y corrige en el esquema, porque el esquema es lo único que el modelo tiene para guiarse.
Esta guía cubre lo que el modelo realmente lee cuando elige una herramienta, cómo escribir nombres y descripciones que discriminen, cómo el diseño de parámetros cambia la tasa de error y cómo probar la selección para que un cambio en la redacción no la rompa silenciosamente. Una vez que tus herramientas se generan a partir de una especificación, como en nuestra guía para convertir una especificación OpenAPI en herramientas de agente, esto se convierte en una cuestión de qué incluir en esa especificación.
Apidog es donde residen las descripciones si tus herramientas provienen de la definición de tu API, por lo que mejorar una mejora la documentación y las herramientas a la vez.
Lo que ve el modelo
En el momento de elegir, el modelo tiene la conversación, el prompt del sistema y una lista de definiciones de herramientas. Cada definición es un nombre, una descripción y un esquema de parámetros. No tiene la documentación de tu API, los comentarios de tu código o el conocimiento tribal de que updateUser es heredado.
Eso significa que cada desambiguación debe escribirse en la definición misma. Tanto la guía de llamada a funciones de OpenAI como la documentación de uso de herramientas de Anthropic señalan lo mismo: la descripción es el texto que más importa en toda la definición, y debe ser prolija en lugar de concisa.
Los errores de selección se presentan en cuatro formas, y cada una tiene una solución diferente.
El modelo elige una herramienta similar cuando dos definiciones se superponen. Soluciona las descripciones para que cada una diga cuándo no usarla. El modelo no elige nada y responde de memoria cuando ninguna descripción coincide con el lenguaje de la tarea. Soluciona esto usando las palabras que usan tus usuarios. El modelo elige la herramienta correcta con argumentos incorrectos cuando los parámetros son ambiguos. Soluciona esto con tipos, enumeraciones y unidades. El modelo encadena mal las herramientas cuando el orden importa y nada lo indica. Soluciona esto indicando el requisito previo en la descripción.
Nombra las herramientas por lo que hacen
Los nombres transmiten más información de lo que su longitud sugiere, porque el modelo los lee primero.
Usa verbNoun, con el mismo estilo en todo el conjunto de herramientas: createOrder, refundOrder, getOrderStatus. La coherencia importa tanto como la elección individual, ya que un conjunto que mezcla order_create, getOrder y refund hace que cada nombre sea ligeramente más difícil de leer.
Sé específico sobre el objeto. search es un mal nombre para una herramienta. searchCustomersByEmail es uno bueno, y le dice al modelo tanto qué busca como cómo.
Evita la jerga interna. Si tu API llama a un cliente "entidad" y a una suscripción "instrumento", el modelo no conectará eso con un ticket que dice "cliente" y "plan". Nombra las herramientas en el lenguaje de la tarea, no en el lenguaje del esquema.
Nunca reutilices un nombre entre contextos. Dos herramientas llamadas list en diferentes espacios de nombres caen en la ambigüedad tan pronto como aparecen en una lista.
Escribe descripciones que discriminen
Una descripción útil responde a cuatro preguntas: qué hace, qué cambia, cuándo usarla y cuándo no.
Aquí hay un par débil:
{ "name": "updateUser", "description": "Updates a user." }
{ "name": "deactivateUser", "description": "Deactivates a user." }
Y un par que realmente separa:
{
"name": "updateUser",
"description": "Updates profile fields on an active user, such as name, email, or timezone. Use for corrections and profile edits requested by the user. Does NOT change account status. To disable an account, use deactivateUser instead. Do not use to close or cancel an account."
}
{
"name": "deactivateUser",
"description": "Disables a user account, revoking all sessions and blocking sign-in. Reversible with reactivateUser. Use when a customer asks to close, cancel, pause, or suspend their account. Does NOT delete data. For permanent deletion use deleteUser, which cannot be undone."
}
Cuatro técnicas están haciendo el trabajo aquí.
Nombra a la herramienta hermana. "Usa deactivateUser en su lugar" resuelve la ambigüedad directamente, en el momento exacto en que el modelo las está comparando.
Incluye el vocabulario del usuario. Las palabras "cerrar", "cancelar", "pausar" y "suspender" aparecen porque son las palabras que surgen en los tickets. Esta es la edición con mayor rendimiento que puedes hacer, y es casi gratuita.
Di lo que no hace. Las declaraciones negativas son más discriminatorias que las positivas, porque las afirmaciones positivas de dos herramientas vecinas tienden a parecerse.
Marca la reversibilidad. El modelo razona sobre el riesgo cuando le dices que hay riesgo. Esto se combina con los patrones de aplicación en nuestra publicación sobre barreras de seguridad para agentes de IA, que es donde reside la verdadera protección.
La longitud está bien. Una descripción de cien palabras que evita una llamada incorrecta a un endpoint destructivo es barata.
Diseña parámetros para que los argumentos incorrectos sean difíciles
Una vez que se elige la herramienta correcta, los argumentos son el siguiente lugar donde las cosas van mal.
JSON Schema te proporciona la mayoría de las restricciones que necesitas aquí, y el vocabulario de validación de JSON Schema merece ser revisado en busca de las palabras clave que tu API de llamada a herramientas soporta.
Usa enumeraciones donde el conjunto esté cerrado. Un parámetro status tipificado como cadena invita a la invención. Tipificado como una enumeración, restringe al modelo a los valores que tu API acepta.
"status": {
"type": "string",
"enum": ["pending", "paid", "refunded", "cancelled"],
"description": "Order status. 'cancelled' means never fulfilled; 'refunded' means fulfilled then reversed."
}
Pon las unidades en el nombre. amount es ambiguo y los modelos adivinarán dólares o centavos de manera inconsistente. amount_cents nunca lo es. Lo mismo ocurre con timeout_seconds, distance_meters y duration_ms.
Proporciona un ejemplo para los formatos de fecha. "description": "Start date in ISO 8601 format, for example 2026-08-26" produce fechas correctamente formateadas con mucha más frecuencia que solo "start date".
Mantén las listas obligatorias honestas. Marcar todo como opcional empuja los fallos al tiempo de ejecución; marcar como obligatorio cosas que la API establece por defecto de forma sensata hace que el modelo invente valores. Ambos son comunes, y ambos aparecen como errores de validación cubiertos por nuestra publicación sobre diseño de errores de API para agentes.
Prefiere lo plano a lo anidado. Un modelo que rellena {"customer": {"address": {"postal_code": "..."}}} comete errores estructurales que no comete en customer_postal_code. Aplanalo en el límite de la herramienta y vuelve a ensamblarlo en tu ejecutor.
Divide las herramientas sobrecargadas. Una herramienta con un parámetro mode que cambia el significado de todos los demás campos es en realidad dos herramientas. Dividirla mejora la selección y simplifica ambos esquemas.
Indica los requisitos previos y el orden
El trabajo de varios pasos falla cuando el modelo no conoce la secuencia. Dilo en la descripción de la herramienta dependiente:
{
"name": "captureCharge",
"description": "Captures a previously authorized charge. Requires an authorization_id from authorizeCharge. Call authorizeCharge first if you do not already have one. Cannot capture more than the authorized amount."
}
Dos líneas, y el problema del orden se maneja donde el modelo ya está leyendo. Esto se aplica a toda la clase: crear antes de actualizar, cargar antes de procesar, autorizar antes de capturar. Si la descripción de un paso dependiente no nombra el paso anterior, espera que el modelo lo omita. Cuando la secuencia abarca múltiples agentes en lugar de múltiples llamadas, se aplican las reglas de traspaso de nuestra publicación sobre paso de contexto entre subagentes.
Prueba la selección como cualquier otro comportamiento
Las descripciones son código y retroceden. Alguien acorta una para que se ajuste a una guía de estilo y el agente comienza a elegir el endpoint incorrecto el próximo martes.
Crea un pequeño conjunto de pruebas de selección. De veinte a cincuenta prompts, cada uno con la herramienta que esperas. Ejecútalos, registra qué herramienta elige el modelo y afirma solo el nombre. Los argumentos varían de una ejecución a otra; la elección no debería. Esta es la forma práctica del enfoque en nuestra guía para probar agentes no deterministas.
Inicialízalo con los casos más propensos a fallar:
- Las dos herramientas más similares en tu conjunto, con prompts que deberían dirigirse a cada una.
- Prompts que usan el vocabulario del cliente en lugar del vocabulario de la API.
- Un prompt que no debería coincidir con nada, donde el comportamiento correcto es preguntar en lugar de forzar una llamada.
- Una herramienta destructiva, donde una elección incorrecta tiene un costo real.
Ejecuta cada prompt varias veces. Una herramienta que gana cuatro de cada cinco es un volado en producción y la descripción necesita trabajo.
Dirige las ejecuciones a mocks para que una prueba de selección nunca toque datos en vivo. Nuestra publicación sobre ejecutar agentes contra mocks en lugar de producción cubre la configuración, y Apidog puede servir esos mocks desde la misma definición de la que se generaron tus herramientas, lo que mantiene el esquema y el comportamiento alineados.
Tres conjuntos que fallan de la misma manera
El conjunto CRUD. Una API expone getUser, listUsers, searchUsers y queryUsers, todos generados a partir de endpoints que crecieron a lo largo de los años. Para un modelo, estos son cuatro nombres para una misma idea. La solución no es tener mejores descripciones en los cuatro; es exponer solo uno de ellos al agente y dejar el resto fuera de la lista de herramientas. Un conjunto curado siempre supera a un conjunto completo.
El conjunto de administración. Las herramientas de lectura y las herramientas destructivas se encuentran una al lado de la otra con el mismo tono: getInvoice, voidInvoice, deleteInvoice. Nada en el texto indica que dos de estas terminan carreras. Agrega la consecuencia a la descripción, márcalas para aprobación y mantén la aplicación en el ejecutor en lugar de confiar en la redacción. El enfoque por capas se encuentra en nuestra publicación sobre evitar que los agentes destruyan tu API.
El conjunto heredado. Dos endpoints hacen el mismo trabajo, uno obsoleto. La especificación todavía lista ambos, por lo que el generador emite ambos, y el agente elige el antiguo aproximadamente la mitad del tiempo. O bien elimina la operación obsoleta de las herramientas generadas o comienza su descripción con las palabras "Obsoleto. Usa createOrderV2 en su lugar." Los modelos respetan esa línea cuando está al principio, y la ignoran cuando está enterrada al final.
Las descripciones son configuración compartida
Una vez que aceptas que las descripciones de las herramientas impulsan el comportamiento, la siguiente pregunta es quién las posee. En la mayoría de los equipos la respuesta es accidental: quienquiera que haya configurado el agente primero, en un archivo en su máquina.
Trata el conjunto de herramientas como un artefacto compartido, revisado como cualquier otra interfaz. Las plataformas construidas alrededor del trabajo de agentes a menudo modelan esto directamente. Un Agente Sharkly es una configuración guardada que cubre instrucciones, Tiempo de Ejecución, Habilidades y repositorios, y compartirlo en un Espacio hace que la configuración de trabajo de una persona sea reutilizable por el equipo. El valor no es el almacenamiento. Es que un cambio de descripción se convierte en una edición revisable que afecta a todos, en lugar de un ajuste local silencioso que hace que el agente de un desarrollador se comporte de manera diferente al resto.
Observa las palabras que traen los usuarios
La brecha más común es el vocabulario. Tu API dice subscription, tus clientes dicen plan, membership y billing. Tu API dice deactivate, ellos dicen cancel, close y turn off.
Recopila el lenguaje real. Extrae las frases principales de los tickets de soporte, los registros de búsqueda o las transcripciones de ejecuciones de agentes fallidas, luego incorpóralas en las descripciones de las herramientas con las que deberían haber coincidido. Esto cuesta una hora y generalmente mejora la precisión de la selección más que cualquier ajuste de esquema.
También presta atención a los fallos. Cuando un agente no elige nada y responde desde su propio conocimiento, eso es una falta de vocabulario, no un fallo de razonamiento. El lenguaje de la tarea nunca se superpuso con el texto de la herramienta, por lo que la herramienta era invisible.
Una lista de verificación para un conjunto de herramientas
- Los nombres siguen una convención
verbNouny nombran un objeto específico. - Cada descripción dice qué cambia, cuándo usarla y cuándo no.
- Las herramientas superpuestas se nombran explícitamente entre sí.
- Las descripciones incluyen las palabras que los usuarios realmente usan, no solo términos internos.
- Las acciones destructivas e irreversibles lo indican en la descripción.
- Las enumeraciones se declaran para cada conjunto cerrado.
- Las unidades y formatos residen en los nombres o descripciones de los parámetros, con ejemplos.
- Las listas de requisitos coinciden con lo que la API realmente impone.
- Las herramientas dependientes nombran su requisito previo.
- Un conjunto de pruebas de selección se ejecuta en CI contra mocks.
El modelo está haciendo coincidencia de patrones con el texto que escribiste. Cuando elige mal, el texto es el primer lugar donde buscar, y usualmente el único lugar que necesitas cambiar. Descarga Apidog si quieres las descripciones, los mocks y las pruebas en un solo proyecto.
Preguntas frecuentes
¿Qué tan larga debe ser la descripción de una herramienta? Lo suficientemente larga para desambiguar, que suelen ser de dos a cinco frases. Las descripciones ocupan contexto, así que recorta las de las herramientas no ambiguas y dedica el espacio a las herramientas que se encuentran una al lado de la otra.
¿Debería incluir ejemplos en la descripción? Sí, para formatos y unidades, donde un ejemplo elimina toda una clase de errores. Omite los ejemplos de uso largos, ya que cuestan contexto y rara vez cambian la selección.
¿Es mejor tener muchas herramientas estrechas o pocas flexibles? Herramientas estrechas, hasta cierto punto. Cada una selecciona de manera más confiable porque hace una cosa. Pasado unas pocas docenas, la lista misma se convierte en el problema y filtras o recuperas, como se cubre en nuestra publicación sobre generar herramientas de agente a partir de OpenAPI.
¿Puedo corregir la selección en el prompt del sistema en su lugar? Parcialmente, y es un paliativo razonable para una o dos confusiones conocidas. No escala, porque el prompt se comparte entre todas las herramientas mientras que la descripción viaja con la herramienta que la necesita.
¿Qué pasa si el modelo sigue inventando valores de parámetros? Restringe el tipo, añade una enumeración y di en la descripción que el valor debe provenir de una llamada anterior en lugar de ser construido. Si aún sucede, valida en el wrapper y devuelve un error nombrando los valores permitidos.
¿Se aplican estas reglas también a los servidores MCP? Sí. Un servidor MCP expone nombres, descripciones y esquemas de la misma forma, por lo que se aplican las mismas reglas de redacción. Nuestra explicación sobre qué es MCP cubre el protocolo en sí.