El agente que entra sin instrucciones
El 1 de junio de 2026 dejé el conector MCP vivo en claude.ai. Está abierto a usuarios gratuitos y a usuarios premium, y desde ese día hay una pregunta a la que no he dejado de darle vueltas: ¿qué ve un agente que entra aquí por primera vez?
Ve una lista de herramientas. Cada una con su nombre y una frase de descripción. Y poco más.
Esa lista le sirve para saber qué puede llamar. No le sirve para saber si merece la pena llamarlo. Son dos cosas distintas y yo las había tratado como una sola.
Un agente así no sabe cuántas cosas puedo responderle, no sabe cuáles se solapan y, sobre todo, no sabe de cuándo son los datos que le voy a devolver. Ese último punto es el que me preocupaba de verdad. Un agente que tiene que decidir si un dato le sirve necesita saber si es de esta semana o de hace medio año. Si no lo sabe, o confía de más o avisa de menos. Las dos salidas son malas.
Un dato viejo presentado como actual es una alucinación con papeles. Y no la comete el modelo: la cometo yo, por no decirle de cuándo es lo que le sirvo. Al contrario también falla: un agente que no sabe la fecha tiende a ser cobarde, a dudar de un dato bueno, a responder con un «depende» que no ayuda a nadie.
Lo que probé primero: escribir mejor
Mi primer reflejo fue el de siempre: si el agente no sabe qué hay dentro, se lo cuento. Me puse a documentar. Una lista de las funciones disponibles, con una línea por cada una explicando qué devuelve y qué necesita. Un documento ordenado, escrito por mí, en el sitio donde yo escribo.
El razonamiento parecía sólido. La documentación es donde un humano aprende a usar un sistema; tarde o temprano un agente pasará por ahí. Documento una vez y el problema queda resuelto para siempre.
Se sostiene hasta que lo piensas dos veces.
El fallo no estaba en el texto, estaba en el sitio
El problema de documentar era doble, y ninguno de los dos tenía que ver con la calidad de lo que escribía.
Primero: el agente no pasa por donde yo escribo. Un agente no lee mi documentación, llama a herramientas. Si lo que necesita saber no está al otro lado de una llamada, para él no existe. Estaba describiendo la casa en una habitación a la que el interesado no tiene llave.
Segundo: un documento es una copia, y una copia se desincroniza. Cada vez que añado una función o cambio lo que devuelve otra, tengo que acordarme de volver a redactar el texto. Al principio te acuerdas. Al cuarto cambio, no. Cada RPC nueva que publicaba era una línea más que sostenía a mano: el texto crecía en la misma proporción que mi deuda. Estaba dibujando a mano el mapa de un territorio que se movía solo.
Y quedaba la pregunta que ningún texto podía contestar: «¿de cuándo son estos datos?». Eso no lo sabe un documento. Lo sabe la base.
La base se describe a sí misma
La salida fue dejar de escribir sobre la base y hacer que la base hablara. Añadí una RPC nueva: describe_conversor().
describe_conversor() no devuelve epígrafes ni códigos. Devuelve un JSONB auto-descriptivo, escrito para que lo lea un agente. Dentro van dos cosas:
- el inventario de RPC a las que puedo responder, es decir, qué sabe hacer la base;
- las marcas de tiempo de frescura de los datos, es decir, de cuándo es lo que te voy a devolver.
Juntas, esas dos piezas contestan a las dos preguntas que un agente se hace antes de fiarse de una herramienta: qué sabe hacer quien está al otro lado y si lo que le va a contar sigue siendo cierto. La primera es cobertura; la segunda es confianza. Sin la segunda, la primera sirve de poco.
Y hay algo mejor que el contenido: de dónde sale. Un agente que acaba de conectarse descubre solo qué hay aquí. No necesita integración previa, no necesita que yo le cuente nada y no necesita acertar por prueba y error. Pide la descripción y recibe el mapa. Y como ese JSONB se construye leyendo el catálogo de la base, no es una copia: es una lectura. No hay nada que mantener a mano, así que no hay nada que se quede viejo.
Reforcé la misma idea por otro camino, el que tenía más a mano: los comentarios del catálogo. Con COMMENT ON dejé descripciones pegadas a las tablas, a las columnas y a las funciones. El texto vive junto al objeto que describe, en el mismo sitio, y viaja con él cuando el esquema cambia. Y como el que describe y el descrito son el mismo esquema, el comentario no puede mentir sobre lo que la base hace: si cambia la función, el comentario está ahí mismo, a la vista, en la misma revisión.
Para separar audiencias, marqué esos comentarios con una etiqueta: [agent]. Lo que lleva esa marca está escrito para que lo lea un agente, no un humano curioseando la estructura. Las dos audiencias no necesitan el mismo texto, y mezclarlas estropea las dos. Podría haber escrito dos documentos separados, uno para cada una, pero entonces volvía al problema de antes multiplicado por dos. La etiqueta consigue lo mismo sin duplicar: un solo comentario por objeto, marcado, y quien lo lee decide si le concierne.
Qué aprendí
Me quedo con una regla: si quieres que un agente use tu sistema sin que nadie le explique nada, no le des documentación — dale una función que se describa a sí misma.
La descripción de un sistema tiene que vivir donde vive el sistema. Todo lo demás es una copia que envejece. Y la frescura de los datos no es un detalle de operación: es información de primera, tan importante como el propio dato. Un agente que sabe qué sabe la base y de cuándo lo sabe puede decidir. Uno que no lo sabe, adivina.
Aprendí la lección con un fallo pequeño y tonto, de esos que no rompen nada y por eso tardas en verlos: había escrito la respuesta en el sitio equivocado. El contenido estaba bien; la ubicación, no.
El conector sigue vivo en claude.ai desde aquel 1 de junio, para cuentas gratuitas y de pago. Si construyes agentes y quieres ver cómo se describe la base por dentro:
https://www.conversoriaecnae.es/mcp
