Por qué las APIs actuales frenan a los agentes de IA

Cuando un agente de IA falla al interactuar con un sistema externo, el instinto habitual es culpar al modelo o al orquestador. Pero hay una tesis que gana peso entre quienes trabajan en el día a día de integraciones: el cuello de botella no está en la IA, sino en los sistemas a los que intenta conectarse. Eso es exactamente lo que argumenta el equipo de AppFactor en un artículo publicado esta semana, usando como ejemplo concreto cómo rediseñaron su herramienta `GetProcInfo3` para hacerla legible por agentes.

La pieza, recogida en Hacker News el 29 de mayo de 2026, parte de una premisa sencilla: las APIs existentes fueron diseñadas para ser consumidas por código determinista escrito por humanos, no por modelos de lenguaje que razonan en lenguaje natural y toman decisiones en tiempo de ejecución.

El problema de fondo: APIs diseñadas para programadores, no para modelos

Una API clásica asume que quien la llama sabe exactamente qué endpoint usar, qué parámetros enviar y cómo interpretar la respuesta. Esa suposición se sostiene cuando el consumidor es un desarrollador que ha leído la documentación. Se rompe cuando el consumidor es un agente que necesita descubrir qué puede hacer, inferir qué herramienta es relevante para una tarea dada y recuperarse de errores semánticos, no solo sintácticos.

Lo que describe el artículo de AppFactor es un proceso de enriquecimiento semántico: añadir a las respuestas de la herramienta metadatos que un agente puede usar para tomar decisiones. No se trata de cambiar la lógica de negocio, sino de hacer que la superficie de la API sea descubrible y significativa para un modelo de lenguaje. El equipo llama a esto «semantic discovery» y lo combina con lo que denominan «AI enrichment», es decir, anotaciones que contextualizan el dato devuelto.

Por qué esto importa ahora, con MCP y Claude Code

Este debate no es nuevo, pero adquiere urgencia concreta en el ecosistema actual. Con Claude Code y el protocolo MCP como estándar para que los agentes llamen herramientas externas, la calidad de esa capa de integración determina directamente qué tan útil resulta un agente en la práctica.

Un MCP server bien construido puede exponer descripciones ricas de sus herramientas, esquemas de parámetros con ejemplos y mensajes de error interpretables. Pero si el sistema subyacente —una API legacy, una base de datos corporativa, un servicio SaaS de hace diez años— devuelve respuestas opacas o requiere conocimiento implícito para ser usado correctamente, ni el mejor MCP server compensa esa fricción.

La aproximación de AppFactor sugiere que el trabajo real no está solo en escribir el wrapper MCP, sino en reformatear la semántica de lo que el sistema devuelve. Eso puede implicar:

• Añadir campos descriptivos junto a identificadores numéricos o códigos internos
• Estructurar las respuestas para que el agente pueda razonar sobre ellas sin contexto adicional
• Documentar los límites y casos de error de forma que el modelo pueda decidir si reintentar, escalar o abandonar

Para quién es relevante

Esta reflexión es especialmente útil para tres perfiles. Primero, equipos de plataforma que están exponiendo servicios internos vía MCP y se preguntan por qué sus agentes siguen fallando aunque el servidor esté técnicamente operativo. Segundo, consultoras e integradores —como nosotros mismos en ElephantPink— que trabajan en conectar sistemas heredados con agentes Claude a medida: la inversión en enriquecer semánticamente las APIs existentes suele ser más productiva que afinar el prompt del agente. Tercero, desarrolladores de plugins y subagentes para Claude Code que quieren que sus herramientas sean robustas frente a instrucciones ambiguas.

Lo que propone el artículo no es glamuroso: es trabajo de fontanería bien hecho. Pero en la práctica, la diferencia entre un agente que funciona en producción y uno que falla de forma impredecible suele vivir exactamente ahí, en esa capa intermedia que nadie quiere tocar.

Dicho esto, el artículo se apoya en un caso propio y con escaso recorrido en la comunidad por el momento —un punto en Hacker News y un comentario al cierre de esta edición—. Vale la pena como referencia de metodología, no como estudio de caso validado a escala.