DEV Community

Cover image for Diseño de Esquemas de Herramientas: Ayuda a Agentes de IA a Seleccionar el Endpoint Correcto
Roobia
Roobia

Posted on Originally published at apidog.com

Diseño de Esquemas de Herramientas: Ayuda a Agentes de IA a Seleccionar el Endpoint Correcto

Cómo mejorar la selección de herramientas en agentes de IA

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", algo que tu API aceptó, aunque significaba algo ligeramente diferente en el sistema.

Nada se rompió. El modelo eligió entre dos opciones plausibles cuyas descripciones no indicaban cuál aplicar. La selección de herramientas es el modo de fallo que muchos atribuyen al modelo, pero que normalmente se corrige en el esquema: el esquema es lo único que el modelo tiene para guiarse.

Prueba Apidog hoy

Esta guía explica:

  • Qué lee realmente el modelo al elegir una herramienta.
  • Cómo escribir nombres y descripciones discriminatorias.
  • Cómo reducir errores mediante el diseño de parámetros.
  • Cómo probar la selección para evitar regresiones silenciosas.

Cuando las herramientas se generan desde una especificación, como en la guía sobre convertir una especificación OpenAPI en herramientas de agente, todo se reduce a decidir qué incluir en esa especificación.

Apidog es donde residen las descripciones si tus herramientas provienen de la definición de tu API. Mejorar una descripción mejora a la vez la documentación y las herramientas.

Selección de herramientas en agentes de IA

Qué ve el modelo

Al elegir una herramienta, el modelo recibe:

  1. La conversación.
  2. El prompt del sistema.
  3. Una lista de definiciones de herramientas.

Cada definición contiene un nombre, una descripción y un esquema de parámetros. El modelo no ve la documentación completa de tu API, los comentarios del código ni el conocimiento interno de que updateUser es una operación heredada.

Por eso, toda desambiguación debe estar en la definición. Tanto la guía de llamada a funciones de OpenAI como la documentación de uso de herramientas de Anthropic destacan la importancia de las descripciones. Deben ser suficientemente detalladas, no simplemente breves.

Los errores de selección suelen aparecer de cuatro formas:

  • Elige una herramienta similar: las definiciones se superponen. Indica cuándo no usar cada una.
  • No elige ninguna: el lenguaje del usuario no coincide con la descripción. Usa el vocabulario real de tus usuarios.
  • Elige la herramienta correcta con argumentos incorrectos: los parámetros son ambiguos. Usa tipos, enumeraciones y unidades.
  • Encadena mal las herramientas: el orden importa, pero no está documentado. Declara los requisitos previos.

Nombra las herramientas por lo que hacen

Los nombres transmiten más información de la que su longitud sugiere porque el modelo los lee primero.

Usa la convención verbNoun de forma coherente:

createOrder
refundOrder
getOrderStatus
Enter fullscreen mode Exit fullscreen mode

No mezcles estilos como order_create, getOrder y refundOrder. La inconsistencia hace que cada nombre sea más difícil de interpretar.

Sé específico sobre el objeto. search es demasiado ambiguo; searchCustomersByEmail comunica qué busca y cómo lo busca.

Evita la jerga interna. Si tu API llama a un cliente “entidad” y a una suscripción “instrumento”, el modelo puede no relacionarlo con un ticket que habla de “cliente” y “plan”. Usa el lenguaje de la tarea, no el lenguaje interno del esquema.

Tampoco reutilices nombres entre contextos. Dos herramientas llamadas list, aunque pertenezcan a espacios de nombres distintos, crean ambigüedad cuando aparecen juntas.

Escribe descripciones que discriminen

Una descripción útil responde a cuatro preguntas:

  1. ¿Qué hace?
  2. ¿Qué cambia?
  3. ¿Cuándo debe usarse?
  4. ¿Cuándo no debe usarse?

Este par es débil:

{ "name": "updateUser", "description": "Updates a user." }
{ "name": "deactivateUser", "description": "Deactivates a user." }
Enter fullscreen mode Exit fullscreen mode

Este par separa claramente las responsabilidades:

{
  "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."
}
Enter fullscreen mode Exit fullscreen mode 
{
  "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."
}
Enter fullscreen mode Exit fullscreen mode

Estas son las técnicas principales:

Nombra la herramienta hermana

“Usa deactivateUser en su lugar” resuelve la ambigüedad justo cuando el modelo compara ambas opciones.

Incluye el vocabulario del usuario

“Cerrar”, “cancelar”, “pausar” y “suspender” aparecen porque son palabras habituales en los tickets. Incorporarlas suele ser la mejora con mayor rendimiento y menor coste.

Di lo que la herramienta no hace

Las declaraciones negativas discriminan mejor que las positivas. Las descripciones de herramientas vecinas suelen parecerse cuando solo explican lo que cada herramienta sí hace.

Marca la reversibilidad

Indica si la acción es reversible, destructiva o permanente. El modelo puede razonar sobre el riesgo cuando esa información está explícita.

Combina esta información con patrones de aplicación como los descritos en la publicación sobre barreras de seguridad para agentes de IA. La protección real debe estar en el ejecutor, no solo en la redacción.

Una descripción de cien palabras que evita una llamada incorrecta a un endpoint destructivo es barata.

Diseña parámetros que dificulten los errores

Después de elegir la herramienta correcta, los argumentos son el siguiente punto de fallo.

JSON Schema proporciona la mayoría de las restricciones necesarias. Revisa su vocabulario de validación y utiliza las palabras clave compatibles con tu API de llamada a herramientas.

Usa enumeraciones para conjuntos cerrados

Un parámetro status tipificado como cadena invita a inventar valores. Una enumeración restringe al modelo a los valores aceptados por tu API:

"status": {
  "type": "string",
  "enum": ["pending", "paid", "refunded", "cancelled"],
  "description": "Order status. 'cancelled' means never fulfilled; 'refunded' means fulfilled then reversed."
}
Enter fullscreen mode Exit fullscreen mode

Incluye las unidades en el nombre

amount es ambiguo: el modelo puede interpretar dólares o centavos. amount_cents no lo es.

Aplica el mismo principio a:

timeout_seconds
distance_meters
duration_ms
Enter fullscreen mode Exit fullscreen mode

Da ejemplos para los formatos

Para una fecha, esto funciona mejor que “start date”:

"description": "Start date in ISO 8601 format, for example 2026-08-26"
Enter fullscreen mode Exit fullscreen mode

Mantén honestas las listas obligatorias

Marcar todo como opcional desplaza los fallos al tiempo de ejecución. Marcar como obligatorio lo que la API establece correctamente por defecto hace que el modelo invente valores. Ambos errores son habituales y están relacionados con la validación descrita en diseño de errores de API para agentes.

Prefiere esquemas planos

Los objetos anidados introducen errores estructurales:

{
  "customer": {
    "address": {
      "postal_code": "..."
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

En el límite de la herramienta, puede ser más fiable usar:

{
  "customer_postal_code": "..."
}
Enter fullscreen mode Exit fullscreen mode

Después, vuelve a ensamblar la estructura en el ejecutor.

Divide las herramientas sobrecargadas

Una herramienta con un parámetro mode que cambia el significado de todos los demás campos suele ser, en realidad, varias herramientas. Dividirla mejora la selección y simplifica los esquemas.

Indica los requisitos previos y el orden

Los flujos de varios pasos fallan cuando el modelo no conoce la secuencia. Declara el requisito previo 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."
}
Enter fullscreen mode Exit fullscreen mode

Dos líneas pueden resolver el problema del orden donde el modelo ya está leyendo. El patrón aplica a muchos casos:

  • 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, el modelo puede omitirlo. Cuando la secuencia abarca varios agentes, consulta las reglas de paso de contexto entre subagentes.

Prueba la selección como cualquier otro comportamiento

Las descripciones son código y también sufren regresiones. Alguien puede acortar una descripción para cumplir una guía de estilo y hacer que el agente elija el endpoint incorrecto la semana siguiente.

Crea un conjunto pequeño de pruebas:

  • Entre 20 y 50 prompts.
  • Una herramienta esperada para cada prompt.
  • Registro de la herramienta elegida.
  • Una aserción que compruebe solo el nombre de la herramienta.

Los argumentos pueden variar entre ejecuciones; la elección no debería hacerlo. Este es el enfoque práctico descrito en probar agentes no deterministas.

Empieza por los casos más propensos a fallar:

  • Las dos herramientas más similares, con prompts dirigidos a cada una.
  • Prompts que usan el vocabulario del cliente y no el de la API.
  • Un prompt que no coincide con ninguna herramienta, donde la respuesta correcta es preguntar.
  • Una herramienta destructiva, donde equivocarse tiene un coste real.

Ejecuta cada prompt varias veces. Si una herramienta gana cuatro de cinco ejecuciones, la selección es prácticamente un volado en producción y la descripción necesita trabajo.

Apunta siempre las pruebas a mocks para que nunca toquen datos reales. La guía sobre ejecutar agentes contra mocks en lugar de producción cubre la configuración. Apidog puede servir esos mocks desde la misma definición que generó las herramientas, manteniendo alineados el esquema y el comportamiento.

Pruebas de agentes con APIs mock

Tres conjuntos que suelen fallar

El conjunto CRUD

Una API expone getUser, listUsers, searchUsers y queryUsers, generados a partir de endpoints que crecieron durante años. Para un modelo, pueden parecer cuatro nombres para la misma idea.

La solución no es escribir mejores descripciones para los cuatro. Expón solo uno al agente y deja los demás fuera de la lista. Un conjunto curado supera a un conjunto completo.

El conjunto de administración

Las herramientas de lectura y las destructivas aparecen juntas con el mismo tono:

getInvoice
voidInvoice
deleteInvoice
Enter fullscreen mode Exit fullscreen mode

Agrega la consecuencia a la descripción, solicita aprobación para las acciones peligrosas y aplica la protección en el ejecutor. No dependas únicamente de la redacción. Consulta cómo evitar que los agentes destruyan tu API.

El conjunto heredado

Dos endpoints hacen lo mismo, pero uno está obsoleto. La especificación todavía lista ambos, así que el generador expone los dos y el agente elige el antiguo aproximadamente la mitad del tiempo.

Elimina la operación obsoleta de las herramientas generadas o comienza su descripción así:

Obsoleto. Usa createOrderV2 en su lugar.
Enter fullscreen mode Exit fullscreen mode

Los modelos suelen respetar esta indicación cuando aparece al principio y pueden ignorarla si está enterrada al final.

Trata las descripciones como configuración compartida

Si las descripciones impulsan el comportamiento, debes decidir quién las mantiene. En muchos equipos la respuesta es accidental: la persona que configuró primero el agente, en un archivo local.

Trata el conjunto de herramientas como un artefacto compartido, revisado igual que cualquier otra interfaz.

Las plataformas orientadas al trabajo con agentes suelen modelarlo directamente. Sharkly guarda una configuración de agente que incluye instrucciones, Tiempo de Ejecución, Habilidades y repositorios. Compartirla en un Espacio convierte la configuración de una persona en un recurso reutilizable por el equipo.

El valor no está solo en el almacenamiento. Un cambio de descripción se convierte en una edición revisable que afecta a todos, en lugar de ser un ajuste local silencioso que hace que cada desarrollador obtenga un comportamiento diferente.

Observa el vocabulario real de los usuarios

La brecha más común es el vocabulario:

API Usuarios
subscription plan, membership, billing
deactivate cancel, close, turn off

Recopila el lenguaje real de los tickets de soporte, registros de búsqueda y transcripciones de ejecuciones fallidas. Después, incorpora esas frases en las descripciones de las herramientas con las que debieron coincidir.

Este trabajo puede tomar una hora y suele mejorar la precisión de selección más que cualquier ajuste de esquema.

También analiza los fallos en los que el agente no elige ninguna herramienta y responde desde su conocimiento. Eso normalmente indica una falta de vocabulario: el lenguaje de la tarea no se superpuso con el texto de la herramienta, por lo que la herramienta era invisible.

Lista de verificación

  • [ ] Los nombres siguen una convención verbNoun y nombran un objeto específico.
  • [ ] Cada descripción explica qué cambia, cuándo usar la herramienta y cuándo no.
  • [ ] Las herramientas superpuestas se nombran explícitamente entre sí.
  • [ ] Las descripciones incluyen las palabras que usan los usuarios.
  • [ ] Las acciones destructivas e irreversibles lo indican claramente.
  • [ ] Cada conjunto cerrado usa una enumeración. selección se ejecutan en CI contra mocks.

El modelo hace coincidencia de patrones con el texto que escribiste. Cuando elige mal, el texto es el primer lugar que debes revisar y, normalmente, el único que necesitas cambiar.

Descarga Apidog para gestionar descripciones, mocks y pruebas en un mismo proyecto.

Preguntas frecuentes

¿Qué tan larga debe ser la descripción de una herramienta?

Lo suficientemente larga para desambiguarla; normalmente, entre dos y cinco frases. Las descripciones consumen contexto, así que acorta las herramientas que no son ambiguas y reserva el espacio para las que compiten directamente.

¿Debería incluir ejemplos?

Sí, especialmente para formatos y unidades, donde un ejemplo elimina una clase completa de errores. Evita ejemplos de uso extensos: consumen contexto y rara vez cambian la selección.

¿Es mejor tener muchas herramientas estrechas o pocas flexibles?

Herramientas estrechas, hasta cierto punto. Cada una se selecciona con más fiabilidad porque hace una sola cosa. Cuando tienes varias docenas, la lista se convierte en el problema: tendrás que filtrarla o recuperar herramientas relevantes, como se explica en generar herramientas de agente a partir de OpenAPI.

¿Puedo corregir la selección en el prompt del sistema?

Parcialmente. Es un paliativo razonable para una o dos confusiones conocidas, pero no escala: el prompt se comparte entre todas las herramientas, mientras que la descripción viaja con la herramienta que necesita la aclaración.

¿Qué hago si el modelo sigue inventando valores?

Restringe el tipo, añade una enumeración e indica que el valor debe provenir de una llamada anterior y no ser construido por el modelo. Si continúa ocurriendo, valida el valor en el wrapper y devuelve un error que enumere las opciones permitidas.

¿Estas reglas también se aplican a 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. Consulta qué es MCP para conocer el protocolo.

Top comments (0)