Diseño de herramientas del catálogo MCP: de docenas de endpoints a un gran conjunto de operaciones

En resumen: esta nota de ingeniería explica por qué UnifAPI expone un gran catálogo de operaciones a través de tres herramientas MCP y por qué las Skills son la capa de cara al usuario por encima de ese catálogo.

El primer catálogo MCP de UnifAPI exponía 73 endpoints. El catálogo actual expone un gran conjunto de operaciones a través de APIs de datos públicos en vivo mediante tres herramientas MCP: list_operations, get_operation y call_api. Hacerlo bien es más difícil de lo que parece: el modelo todavía necesita descubrir la operación correcta, inspeccionar el esquema y hacer una llamada limpia. Esto es lo que aprendimos sobre nombres, descripciones, esquemas de parámetros y los modos de fallo que no aparecen hasta que tienes docenas de operaciones en vivo.

Por qué un gran conjunto de operaciones cambia el producto

Con 5-10 operaciones, MCP "simplemente funciona" — el modelo busca en el catálogo, elige una y la llama. Con 20-30, el nombre de las operaciones empieza a importar; ves que el modelo elige ocasionalmente la ruta cercana pero equivocada. Con más de 50, el propio catálogo pasa a ser estructural.

El número seguirá creciendo, pero la lección de producto ya es clara: a medida que sube el número de operaciones, las Skills se vuelven más importantes porque ocultan la navegación del catálogo detrás de un resultado de tarea.

Nombres de las operaciones: legibles por el agente, no por el humano

Nuestras etiquetas de operación siguen un patrón: plataforma, verbo, sustantivo. TikTok search videos, Reddit get post, LinkedIn search people. Prolijo, pero inequívoco. El modelo elige la operación correcta porque el nombre se lee como un fragmento de frase, no como un identificador de código.

Al principio probamos convenciones más cortas —tiktok.search, reddit.post— y vimos que el modelo elegía mal en pares cercanos ("search" en TikTok frente a "search" en Reddit cuando el usuario decía "search"). El prefijo de plataforma en el título de la operación desambigua sin que el modelo tenga que razonar sobre ello.

Las descripciones son el prompt

Cada descripción de operación tiene una o dos frases. El modelo las ve durante el descubrimiento y la inspección. Dos patrones que se ganan sus tokens: empezar con el resumen verbo-objeto en las primeras 12 palabras, y terminar con una pista de cuándo usarla.

Bien: "Search TikTok for videos matching a keyword or hashtag. Use when the user wants short-video discovery on a topic." Mal: "This endpoint allows you to query the TikTok platform and retrieve a paginated list of videos that match a search term, optionally filtered by various parameters including ..." La segunda es técnicamente más completa y es el compromiso equivocado en un catálogo grande.

Esquemas de parámetros: mantenlos planos

call_api toma un objeto plano: path, method, query y body. Los campos obligatorios primero, los opcionales después. La razón es simple: los esquemas JSON anidados confunden al generador de llamadas a herramientas del modelo. Hemos visto a Claude entender correctamente un parámetro y luego emitirlo en el nivel de anidamiento equivocado porque el esquema parecía ramificado.

Cuando una operación necesita genuinamente una entrada polimórfica (buscar por palabra clave O por hashtag), get_operation necesita mostrar un ejemplo de llamada concreto. Un ejemplo concreto le gana a un esquema ramificado siempre.

En qué nos equivocamos

Tres errores que vale la pena nombrar. Primero, dejamos que Twitter y Reddit tuvieran descripciones casi idénticas para sus respectivas operaciones de búsqueda, y el modelo empezó a elegir una cuando el usuario pedía explícitamente la otra. Se solucionó haciendo que cada descripción nombrara su plataforma explícitamente en la primera frase.

Segundo, durante un tiempo devolvíamos los mensajes de error de origen tal cual. Algunos de ellos hacen referencia a conceptos específicos de la plataforma que el modelo no entiende, y el agente entraba en bucle intentando arreglar un problema que nuestra envoltura estaba ocultando. Se solucionó normalizando los errores en un vocabulario cerrado como unauthorized, validation_error, invalid_id, not_found, rate_limited y upstream_unavailable.

Tercero, documentamos de menos la paginación en algunas operaciones, y el modelo volvía a llamar desde el cursor 0 en cada bucle en lugar de avanzar. Se solucionó detallando el contrato de paginación en los propios datos de la operación inspeccionada, no solo en la especificación.

Preguntas abiertas

¿En qué punto particionamos el catálogo? Un gran conjunto de operaciones cabe hoy detrás de un único servidor MCP, pero el catálogo puede acabar necesitando filtros por categoría o servidores específicos por categoría para que el modelo solo cargue lo que necesita.

Todavía no conocemos la respuesta correcta. Si estás desplegando hoy agentes que consumen muchas operaciones de UnifAPI, queremos saber cómo se ve la latencia de selección de operaciones por tu lado — escríbenos a hello@unifapi.com.

Qué leer a continuación

Envoltura de respuesta unificada - empareja el descubrimiento de herramientas con el contrato de respuesta.

Conecta UnifAPI MCP - muestra la ruta de configuración de cara al operador.

Recursos para desarrolladores - reúne las especificaciones legibles por máquina y la documentación.