Rúbrica de preparación para IA — 28 criterios
AgentFit puntúa cada sitio auditado frente a 28 criterios agrupados en seis categorías que suman 100 puntos. Cada criterio tiene una especificación explícita: qué comprueba la auditoría, cómo se traducen los niveles de puntuación a puntos y una pista breve para cerrar la brecha. La especificación es determinista y está totalmente replicada en código Go. Lee el artículo de metodología para conocer el enfoque.
Más allá de los 28 criterios puntuados, AgentFit también detecta señales emergentes como el soporte de WebMCP y la presencia de un servidor MCP. WebMCP · MCP.
En esta página
Qué significa realmente la preparación para la IA
Un agente lee tu documentación por HTTP, no en un navegador con una persona detrás. No ejecuta tu JavaScript, no hace scroll, no pasa el cursor sobre una pestaña para desplegar la lista de endpoints y no le pregunta a un compañero cuál es el límite de peticiones. Descarga, analiza y o bien encuentra un contrato utilizable, o se rinde y adivina. La preparación para la IA es la parte de ese recorrido que una máquina completa sin ayuda.
Es medible porque cada paso de ese recorrido es un hecho HTTP observable. Existe /llms.txt y se puede analizar. La página lleva una URL canónica absoluta. El documento OpenAPI es válido y describe sus esquemas de respuesta. El método, la ruta y un ejemplo funcional aparecen en el HTML crudo que llega antes de que se ejecute ningún script. Nada de esto exige juzgar si la prosa es buena. AgentFit comprueba 28 hechos de este tipo y para cada uno informa de lo que vio, con la URL que descargó y el fragmento que sirve de evidencia.
Cómo se calcula la puntuación
Cada uno de los 28 criterios tiene una escalera de niveles enteros y un peso. Un criterio devuelve un estado — presente, parcial, ausente, no aplicable o error — y una puntuación entre cero y su peso. Las 28 puntuaciones se agrupan en seis categorías que suman exactamente 100. «No aplicable» y «error» valen cero los dos, pero se etiquetan por separado a propósito: «no pudimos medirlo» no es la misma afirmación que «no está», y fundirlos permitiría que una descarga bloqueada se hiciera pasar por un hallazgo.
Los pesos no son cuestión de gusto editorial. Cada uno sale de una regla escrita antes de calcular los números: un criterio gana peso cuando separa sitios que empatan en el resto de la rúbrica, y pierde peso cuando su puntuación la decide sobre todo la plataforma de documentación que usa el sitio. Un punto que consigues por elegir cierto alojamiento de docs es un punto sobre tu alojamiento, no sobre tu documentación. La regla, la métrica y el vector final de pesos se subieron al repositorio antes de la calibración; el orden de los commits es la pista de auditoría, y ese mismo procedimiento ya rechazó una vez la hipótesis de su propio autor.
La auditoría es determinista: el mismo sitio descargado dos veces produce un JSON idéntico byte a byte. Durante la puntuación no se ejecuta ningún modelo de lenguaje: dos clasificadores pequeños, para el realismo de los ejemplos y la completitud de los endpoints, van compilados en el binario y versionados con él, así que un reentrenamiento no puede mover tu puntuación en silencio. Cuando cambia la propia regla de medida, se incrementa la versión de la rúbrica y queda sellada en la ejecución, y comparar dos ejecuciones puntuadas con versiones distintas se rechaza en lugar de presentarlo como un cambio en tu sitio.
Pesos de las categorías. La tercera columna es la pregunta que la categoría responde por ti.
| Categoría | Peso | Qué responde |
|---|---|---|
| A — Descubrimiento | 14 | ¿Puede un agente encontrar tu documentación en URLs predecibles? |
| B — Elementos de página | 21 | ¿Puede un parser procesar directamente el contenido de cada página? |
| C — Contrato de API | 17 | ¿Se publica el contrato de la API como una especificación legible por máquina? |
| D — Contenido | 23 | ¿Cada página de endpoint aporta contexto suficiente para usarlo? |
| E — Renderizado e higiene | 21 | ¿El sitio es estable y usable sin JavaScript? |
| F — Capacidad de agente | 4 | ¿El sitio expone superficies nativas para agentes (llms.txt, WebMCP, MCP, accesibilidad)? |
A — Descubrimiento · 14/100
¿Puede un agente encontrar tu documentación en URLs predecibles?
La descubribilidad abarca todo lo que un agente encuentra antes de leer una sola página de documentación: un índice /llms.txt en la raíz del host, un agregado a texto completo /llms-full.txt, un robots.txt que se posiciona explícitamente sobre los rastreadores de IA, un sitemap con páginas reales en vez de archivos de etiquetas, y etiquetas en la portada que apuntan a un gemelo en markdown. Es la categoría más barata del tablero — cada artefacto es un fichero estático generado en el build — y es la que más a menudo se deja vacía.
A1 · llms.txt en la raíz del host conforme a la especificación de llmstxt.org
los agentes (y las personas que llegan por primera vez a un sitio) necesitan un índice único y predecible de dónde está la documentación. /llms.txt es la convención propuesta por Anthropic y la comunidad de llmstxt.org: un único archivo Markdown en la raíz del host con el mapa de la documentación.
Puntuación. 2 = H1 + ≥1 H2 + ≥3 enlaces + todos responden · 1 = cualquier archivo con un H1 (degradado desde 2 si los enlaces no responden) · 0 = ausente o shell HTML.
Corrección. Publica /llms.txt en la raíz del host con un título `# H1`, encabezados de sección `## H2` y al menos tres enlaces Markdown en viñetas que apunten a páginas de documentación concretas. Consulta la especificación en https://llmstxt.org.
A2 · Existe llms-full.txt o agregados de LLM por sección
/llms-full.txt es el volcado de texto completo de tu documentación en un solo lugar: los agentes basados en grandes modelos de lenguaje lo prefieren antes que rastrear 200 páginas HTML. Las variantes por sección (/llms-api.txt, etc.) también sirven.
Puntuación. 3 = /llms-full.txt en la raíz del host, >1 KB · 2 = agregado por sección hallado a través de llms.txt · 0 = ninguno, o shell SPA en /llms-full.txt.
Corrección. Genera /llms-full.txt en tiempo de compilación (existen complementos para mkdocs/docusaurus) y sírvelo como text/plain. Mantenlo por debajo de 100 MB para que los agentes puedan descargarlo sin streaming.
A3 · robots.txt declara una política de bots de IA y un Sitemap absoluto
todo rastreador de IA (GPTBot, ClaudeBot, Google-Extended, PerplexityBot, CCBot) lee /robots.txt antes de rastrear. Un Allow/Disallow explícito por UA más una directiva `Sitemap:` absoluta elimina la ambigüedad tanto sobre la indexación como sobre qué indexar.
Puntuación. 3 = directiva de UA de bot de IA explícita Y línea Sitemap: absoluta · 2 = solo directiva de bot de IA · 1 = solo Sitemap absoluto · 0 = ninguno, o 404.
Corrección. Añade `User-agent: GPTBot\nAllow: /` (o Disallow según dicte tu política) para cada bot de LLM importante, además de una línea `Sitemap: https://example.com/sitemap.xml`. La directiva `Content-Signal:` de Cloudflare también cuenta.
A4 · sitemap.xml: bien formado, URLs absolutas, poco ruido de taxonomía
los sitemaps indican a los rastreadores qué indexar y con qué frecuencia cambia. Un `<urlset>` bien formado con URLs `<loc>` absolutas a lo largo de muchas páginas distintas señala una cobertura real; un sitemap mínimo con una sola URL (o una con un 70 % o más de ruido /tag/ /category/) no aporta ninguna señal.
Puntuación. 3 = bien formado + ≥3 rutas distintas + <30 % de basura de taxonomía · 2 = escaso (<3 rutas) o entre 30-70 % de basura · 1 = solo bien formado · 0 = 404 o error de análisis.
Corrección. Genera /sitemap.xml en tiempo de compilación, incluye cada página de documentación con `<loc>` como URLs absolutas y excluye las variantes /tag/, /category/, /author/, /page=. Referéncialo desde robots.txt con una línea `Sitemap:` absoluta.
A5 · Etiquetas de descubrimiento en la página de inicio: alternativa markdown + OpenGraph
las etiquetas de descubrimiento permiten a los agentes encontrar la versión markdown de una página sin una solicitud aparte, y OpenGraph convierte los enlaces de documentación compartidos en vistas previas enriquecidas en Slack/Discord/Twitter. Ambas señalan conciencia de los consumidores automáticos.
Puntuación. 2 = `<link rel=alternate type=text/markdown>` + ≥3 propiedades `og:` distintas · 1 = solo alternativa markdown O solo OpenGraph · 0 = ninguna.
Corrección. Añade `<link rel="alternate" type="text/markdown" href="/page.md">` junto a tu enlace canonical, y asegúrate de que `og:title`, `og:description`, `og:image` (mínimo 3 propiedades) estén definidas en la página de inicio.
B — Elementos de página · 21/100
¿Puede un parser procesar directamente el contenido de cada página?
Los elementos de página deciden si una página suelta se puede ingerir sin adivinar: un compañero markdown limpio servido en .md o mediante Accept: text/markdown, un JSON-LD que se analiza y declara un tipo, una URL canónica absoluta, una fecha de modificación legible por máquina y un elemento main o article que marca dónde acaba el contenido y empieza la navegación. Los agentes deduplican por la canónica y deciden qué volver a descargar por la fecha; sin esas señales tu página es un muro indiferenciado de divs.
B1 · El .md gemelo de las páginas de documentación devuelve markdown limpio
navegar 200 páginas HTML para leer tu documentación está bien para las personas; para los agentes supone un coste de tokenización un orden de magnitud mayor. Un gemelo markdown por página permite a los agentes extraer solo la prosa.
Puntuación. 7 = 3/3 páginas muestreadas tienen un gemelo .md funcional · 4 = 2/3 · 2 = 1/3 · 0 = 0/3.
Corrección. Sirve `{page}.md` (o `{page}/index.md`) junto a cada página HTML, O bien admite la negociación de contenido `Accept: text/markdown` que devuelva `Content-Type: text/markdown`. Tanto mkdocs-material como docusaurus tienen complementos para ello.
B2 · JSON-LD con @type válido en la página de inicio y en una página de documentación de muestra
JSON-LD es la forma compatible con schema.org de declarar «esta página es un Article» / «este producto es una SoftwareApplication». Los motores de búsqueda, los agentes y los extractores de datos estructurados se basan en él.
Puntuación. 4 = JSON-LD analizable con `@type` en AMBAS, la página de inicio y una página de documentación de muestra · 3 = una de las dos · 0 = ninguna.
Corrección. Incrusta `<script type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle",...}</script>` en cada página de documentación. El tipo `WebApplication` encaja bien para la página de inicio.
B3 · <link rel=canonical> absoluto en la página de inicio y en una página de muestra
los enlaces canonical resuelven de forma determinista la cuestión de «¿es esta la versión http o https, con o sin barra final, con o sin parámetros?». Sin ellos, los agentes pueden indexar el mismo contenido bajo varias URLs.
Puntuación. 3 = canonical absoluto en AMBAS, la página de inicio Y una página de muestra · 2 = solo la página de inicio · 1 = presente pero relativo · 0 = ausente.
Corrección. Añade `<link rel="canonical" href="https://example.com/page">` al `<head>` de cada página. La URL debe incluir el esquema + el host (los canonical relativos son HTML válido pero anulan el propósito para los agentes entre hosts).
B4 · Actualidad: dateModified (JSON-LD) o cabecera Last-Modified
los agentes (y los motores de búsqueda) reducen su confianza en una documentación que no declara cuándo se actualizó por última vez. Una página de documentación de 2019 sin señal de actualidad es indistinguible de una actualizada ayer.
Puntuación. 2 = `dateModified` en JSON-LD O cabecera HTTP `Last-Modified` presente · 0 = ninguna.
Corrección. Incluye `"dateModified": "2026-05-28"` en tu bloque JSON-LD, o haz que tu CDN/servidor emita una cabecera HTTP `Last-Modified`. El uso de plantillas en tiempo de compilación lo hace gratis en la mayoría de los generadores de sitios estáticos.
B5 · Taxonomías legibles por máquina (keywords, etiquetas, categorías)
una documentación etiquetada ayuda a los agentes a filtrar («muéstrame las páginas relacionadas con auth») sin analizar toda la prosa. `<meta name="keywords">`, `keywords` en JSON-LD o URLs al estilo `/tags/` cuentan todas.
Puntuación. 2 = al menos una señal de taxonomía presente (meta keywords, keywords en JSON-LD o patrones de enlace /tags|/categories|/topics/) · 0 = ninguna.
Corrección. Añade `<meta name="keywords" content="api,auth,oauth">` a cada página, O incluye un array `keywords` en tu JSON-LD, O organiza el contenido bajo prefijos de URL `/topics/` o `/tags/`.
B6 · <main> o <article> envuelve la prosa del contenido principal
los contenedores semánticos de HTML5 permiten a los agentes (y a los lectores de pantalla) descartar la navegación/el pie/las barras laterales y leer solo la prosa de la documentación. Una página cuyo cuerpo es todo `<div>` exige adivinar.
Puntuación. 2 = texto de `<main>` >200 caracteres Y texto de `<article>` >100 caracteres · 1 = solo `<main>` O solo `<article>` · 0 = ninguno.
Corrección. Envuelve la prosa principal de tu página en `<main>` (o `<article>` para páginas de documentación individuales). Evita usarlos para barras laterales o navegación: están pensados para el contenido real.
C — Contrato de API · 17/100
¿Se publica el contrato de la API como una especificación legible por máquina?
La categoría del contrato de API plantea una sola cosa: si existe una especificación que un agente pueda encontrar y en la que pueda confiar. C1 es el criterio más pesado de la rúbrica, con 8 puntos, repartidos entre encontrar el documento en una URL descubrible y que sea un OpenAPI 3.x válido con info, rutas y esquemas de respuesta. La división es deliberada: un fichero que existe pero no describe qué se devuelve es medio contrato. Una especificación válida vale más que cualquier página de prosa, porque de ella se generan un cliente, una batería de pruebas y definiciones de herramientas sin leer la documentación.
C1 · Especificación OpenAPI / Swagger / AsyncAPI — encontrada y válida
la especificación OpenAPI es EL contrato legible por máquina de una API REST: un agente que encuentra una VÁLIDA genera clientes, pruebas y docs sin leer HTML. v3 fusiona descubrimiento y validez en un criterio.
Puntuación. 8 = OpenAPI 3.x válida (info, ≥1 path, esquemas de respuesta en ≥30% de operaciones) · 3 = especificación hallada en una URL accesible pero no válida 3.x (incl. Swagger 2.0) · 0 = nada · error si no se pudo obtener la página de inicio.
Corrección. Publica la especificación en `/openapi.json` o `/openapi.yaml` en la raíz (o anúnciala vía RFC 9727 api-catalog `service-doc`). Hazla OpenAPI 3.x y da a cada operación un esquema `responses` — eso otorga los 8 puntos.
C2 · Colección de Postman o SDKs con descarga/fork descubrible
una especificación OpenAPI permite a los agentes generar un cliente; una colección de Postman curada o un SDK preconstruido permiten a las PERSONAS probar la API en 30 segundos. Ambos señalan inversión en la experiencia de quien desarrolla.
Puntuación. 4 = enlace a colección de Postman Y ≥1 enlace a registro de SDK · 3 = Postman O ≥2 enlaces a SDK · 2 = 1 enlace a SDK · 0 = nada.
Corrección. Publica un botón «Run in Postman» que enlace a god.gw.postman.com/run-collection, y enlaza al menos un SDK oficial de npm/PyPI/RubyGems/etc. directamente desde la página de inicio de tu documentación.
C3 · Las páginas de endpoint muestran método, URL, tipos, obligatoriedad y ejemplos
una página de documentación que solo dice «llama a /users» es inútil sin el método, los tipos de parámetro, los campos obligatorios y una solicitud/respuesta de ejemplo. Los agentes (y las personas) necesitan los cinco para hacer una llamada funcional.
Puntuación. 5 = la mayoría de las páginas muestreadas se clasifican como `complete` por el modelo de ML · 3 = la mayoría `partial` (o 2 complete + 1 absent) · 1 = la mayoría `absent` · 0 = no se hallaron páginas candidatas.
Corrección. En cada página de endpoint incluye: método HTTP + path, una tabla de parámetros con tipos e indicadores de obligatoriedad, un ejemplo con curl y un ejemplo de respuesta JSON con código de estado. Las tablas de parámetros estilo Markdown y los bloques JSON en `<pre>` se clasifican con claridad.
D — Contenido · 23/100
¿Cada página de endpoint aporta contexto suficiente para usarlo?
Contenido es la categoría más grande y la única que no se arregla en un fichero de configuración. Comprueba si las páginas de endpoint traen ejemplos ejecutables en más de un lenguaje, si esos ejemplos usan valores que parecen datos reales en vez de foo y example.com, si los errores están catalogados con códigos y causas, si están documentadas la autenticación y los límites de peticiones, y si un mismo concepto se llama igual en todo el sitio. Los agentes fundamentan sus respuestas en tus ejemplos; un fragmento lleno de marcadores acaba copiado literalmente en el código generado.
D1 · Los ejemplos de código incluyen curl Y al menos un SDK de un lenguaje
los ejemplos con curl son comprobables universalmente; los ejemplos con SDK muestran el uso idiomático. Juntos cubren tanto la necesidad de «¿puedo probar esto rápido?» como la de «¿cómo lo integro?».
Puntuación. 4 = curl Y un bloque de SDK de un lenguaje en ≥1 página · 2 = solo curl · 1 = solo SDK · 0 = ninguno.
Corrección. Añade un bloque de código con pestañas por endpoint con al menos curl + el lenguaje de SDK que más usas (Python o JavaScript). Usa `<code class="language-python">` o `language-bash` para que tanto los resaltadores de sintaxis como nuestro clasificador lo detecten.
D2 · Ejemplos realistas (no foo/bar/example.com)
`/users/{id}` con `id = 1` y `email = [email protected]` obliga a quien lee a imaginar cómo son los datos reales. Los placeholders realistas (`[email protected]`, `org_2N5x...`) reducen la fricción y evitan accidentes al pegar desde la documentación.
Puntuación. 4 = el modelo de ML dice que <20 % de los bloques de código están cargados de placeholders · 3 = 20-40 % · 2 = 40-60 % · 1 = 60-80 % · 0 = >80 % o sin bloques de código.
Corrección. Reemplaza `foo`/`bar`/`example.com`/`your_api_key`/`<string>` por valores de aspecto realista (el `pk_test_51N5...` de Stripe, el `+14155552671` de Twilio). No uses datos reales de clientes, pero imita su forma.
D3 · Catálogo de errores con códigos HTTP + motivos
cuando una integración se rompe a las 3 de la madrugada, quien desarrolla necesita saber qué significa realmente `403 - resource_not_owned` sin abrir un ticket. Una página de referencia de errores dedicada marca la diferencia entre un arreglo de 5 minutos y media hora de depuración.
Puntuación. 3 = página de errores dedicada (≥3 códigos con explicaciones) · 1 = códigos de error documentados de forma intercalada entre páginas · 0 = ninguno.
Corrección. Publica `/errors` (o `/reference/errors`) enumerando cada estado HTTP que devuelves + los códigos de error a nivel de aplicación + una causa de una frase para cada uno. Las tablas funcionan bien; también las listas de definición `<dl>`.
D4 · Autenticación Y límites de tasa documentados
la autenticación es lo mínimo; los límites de tasa son lo que permite a quien desarrolla saber si su integración sobrevivirá a la carga de producción. Ambos pertenecen a una página de documentación de primer nivel descubrible desde la página de inicio.
Puntuación. 3 = autenticación y límites de tasa documentados · 2 = solo autenticación · 1 = solo límites de tasa · 0 = ninguno.
Corrección. Añade páginas `/authentication` (flujos bearer / API-key / OAuth) y `/rate-limits` (req/min, cabeceras como `X-RateLimit-Remaining`, semántica de reintento del 429). Cada una necesita al menos 200 caracteres de contexto, no solo un fragmento de código.
D5 · Glosario O terminología coherente entre páginas
¿es un «workspace», un «team» o una «organisation»? Elegir un término y mantenerlo en toda la documentación previene toda una clase de tickets de soporte del tipo «¿qué significa X aquí?». Lo mejor es un glosario dedicado; un uso coherente es aceptable.
Puntuación. 3 = /glossary dedicado con ≥3 pares estructurados de término/definición · 2 = sin glosario pero la terminología se mantiene coherente entre páginas (≥80 % de la variante dominante) · 1 = existe un enlace al glosario pero el contenido es escaso · 0 = ninguno.
Corrección. Publica `/glossary` como un `<dl>` con pares `<dt>término</dt><dd>definición</dd>` (o una tabla de 2 columnas con definiciones de ≥50 caracteres). Usa la misma capitalización/ortografía para cada término en todas las páginas.
D6 · Endpoints obsoletos / en beta marcados en texto plano
quien pegue tu ejemplo de código de 2022 en un proyecto de 2026 no debería descubrir en tiempo de ejecución que el endpoint está obsoleto. Marcadores explícitos de `deprecated` / `beta` / `sunset` en la documentación ahorran dolores de cabeza en la migración.
Puntuación. 2 = `deprecated` en la especificación OpenAPI O en ≥2 páginas de muestra cerca de los encabezados de endpoint · 1 = se hallan palabras clave beta/experimental pero ninguna obsolescencia · 0 = ninguno.
Corrección. Marca cada endpoint obsoleto con `deprecated: true` en OpenAPI Y una insignia o advertencia visible en la documentación HTML (el `<Warning>` de Mintlify, la sintaxis de advertencias de Docusaurus, etc.). Lo mismo para los endpoints en beta: visibles en la prosa, no solo en la especificación.
E — Renderizado e higiene · 21/100
¿El sitio es estable y usable sin JavaScript?
Renderizado e higiene trata de si algo de lo anterior sobrevive al contacto con un cliente HTTP normal. E1 es el criterio de paso: si el contenido no está en el HTML que llega antes de que se ejecute JavaScript, el agente ve una cáscara de aplicación vacía por muy buena que sea la documentación. El resto de la categoría cubre URLs estables ante mudanzas, una versión de API explícita, enlaces internos que de verdad resuelven, condiciones de uso declaradas y controles con nombres accesibles a los que un agente pueda apuntar cuando opera la página en vez de leerla.
E1 · Contenido visible en HTML plano sin JavaScript (criterio de bloqueo)
este es el criterio DE BLOQUEO. Si tu documentación solo se renderiza después de que se ejecute JavaScript (shell de single-page-app), los agentes que descargan el HTML en bruto no ven nada. Los rastreadores web + scrapers + curl + la mayoría de los recolectores de IA no ejecutan JS.
Puntuación. 6 = texto del cuerpo >500 caracteres en al menos una página (la de inicio o 2 subpáginas) en los modos de UA · 3 = la página de inicio pasa pero las subpáginas son SPA · 0 = shell SPA en todas partes, o trampa de shell uniforme (3+ URLs devuelven un cuerpo idéntico).
Corrección. Sirve HTML prerenderizado en URLs estáticas. Si usas Next.js/Nuxt/SvelteKit, habilita SSG o SSR para la sección de documentación. Los shells de single-page-app (React SPA, Vue SPA sin SSR) suspenden este criterio y arrastran a cero en cascada muchos otros.
E2 · URLs estables: las redirecciones 301 preservan las rutas antiguas
cuando reorganizas la documentación, los enlaces antiguos no deberían dar 404, sino redirigir con 301 a la nueva URL. Las URLs estables son lo que permite que los enlaces internos de blogs, Stack Overflow y marcadores sobrevivan a tu refactorización.
Puntuación. 2 = redirección 301/308 estable en ≥1 de 2 variantes de URL muestreadas · 1 = patrón de alias canonical (200 con `<link rel=canonical>`) · 0 = 302 (no permanente), 404 o sin redirección.
Corrección. Cuando cambies la URL de un documento, añade una redirección 301 de la ruta antigua a la nueva. Los generadores de sitios estáticos lo gestionan mediante configuraciones `_redirects` (Netlify) o `redirects:` en `vercel.json` (Vercel).
E3 · Versión de API explícita en la ruta de la URL, el encabezado o la especificación OpenAPI
`/v1/users` frente a `/v2/users` es la forma barata de versionar una API Y de hacerlo evidente para los agentes. Los metadatos de versión que solo están en una cabecera (y no en la ruta ni en el encabezado de la documentación) son invisibles para los rastreadores.
Puntuación. 2 = versión en la estructura de URL propia de la documentación (URL del sitemap o de la spec OpenAPI: `/v1/`, `/2024-01-15/`) · 1 = versión en la URL de un endpoint documentado (ejemplos curl/código), en `info.version` de OpenAPI, o en un encabezado `<h1>`/`<h2>`/pie de página · 0 = ninguna.
Corrección. Prefija las rutas de tu API con `/v1/`, `/v2/` y muéstralas en tus ejemplos curl/código; O establece un `info.version` no vacío en tu especificación OpenAPI. Las APIs versionadas por fecha (`/2024-01-15/users`) también cuentan.
E4 · Comprobación puntual de 5 enlaces internos → todos devuelven 200
los enlaces internos podridos son el modo de fallo de documentación más común tras años de cambios. Una comprobación puntual de 5 enlaces atrapa los peores casos (4xx/5xx en enlaces que están en tu propia página de inicio) sin intentar rastrear cada enlace.
Puntuación. 2 = 5/5 de los enlaces del mismo host muestreados devuelven 200 · 1 = 4/5 · 0 = ≤3/5, O se hallaron menos de 5 enlaces distintos del mismo host en la página de inicio.
Corrección. Ejecuta un verificador de enlaces como parte de tu CI (lychee, htmltest, linkinator). Para los enlaces más transitados de la página de inicio, corrige cualquier 404 antes de publicar. Cinco enlaces funcionales desde la página de aterrizaje es el mínimo imprescindible.
E5 · Términos de uso: TOS / licencia / política de IA explícitos
sin un TOS o una política de uso de IA explícita, todo scraper de LLM tiene que adivinar tu postura. Añadir una página `/terms` o `/license` sustancial, especialmente con palabras clave de IA/ML, hace que la política sea legible por máquina.
Puntuación. 2 = página de TOS hallada Y contiene palabras clave de política de IA/ML en el contenido principal · 1 = TOS hallado (sustancial pero sin palabras clave de IA, o enlace presente pero página 404/escasa) · 0 = sin enlace a TOS.
Corrección. Publica `/terms` (o `/legal`, `/license`) con al menos 1000 caracteres de texto de política. Incluye lenguaje explícito sobre el scraping de IA, el entrenamiento de modelos y el acceso automatizado: aunque lo permitas todo, decirlo es la señal.
E6 · Accesibilidad para agentes: nombres estáticos + validez ARIA
un agente de IA opera una página mediante su árbol de accesibilidad: cada botón, enlace, campo e imagen necesita un nombre localizable. v3 traslada este criterio de la categoría F a E junto a E1, porque evalúa la página renderizada, no una superficie de descubrimiento.
Puntuación. 4 = 0 violaciones (y ≥1 elemento que comprobar) · 2 = 1–2 · 1 = 3–5 · 0 = ≥6 · not_applicable si no hay nada que nombrar · error si no se pudo escanear la página. Heurística estática (sin axe-core/headless).
Corrección. Da a cada `<button>`/`<a>`/icono un nombre accesible; asocia `<label>` a los campos; añade `alt` a las imágenes y `<title>` a los SVG en línea; elimina `tabindex` positivos; corrige `aria-*` y roles mal escritos.
F — Capacidad de agente · 4/100
¿El sitio expone superficies nativas para agentes (llms.txt, WebMCP, MCP, accesibilidad)?
Capacidad de agente registra las superficies explícitas para agentes: una superficie de herramientas WebMCP en la página, declarativa o por JavaScript y un servidor MCP anunciado cuyos metadatos OAuth cumplen las RFC 9728 y RFC 8414. Es deliberadamente pequeña: cuatro puntos sobre cien. Ambas especificaciones son jóvenes y siguen cambiando, la adopción fuera de un puñado de plataformas de documentación se mide en porcentajes de un dígito, y penalizar a todo sitio por no haber implementado un estándar experimental diría más de nuestro entusiasmo que de su documentación. El peso crecerá cuando crezca la adopción.
F2 · Superficie de herramientas WebMCP para agentes del navegador
WebMCP permite a una página exponer herramientas invocables a un agente de IA que se ejecuta en la pestaña: mediante marcado declarativo `<form toolname tooldescription>`, la API imperativa `navigator.modelContext` o un polyfill. F2 premia cualquier superficie detectada; la comprobación de esquema de los formularios declarativos va a los diagnósticos y no cambia el punto.
Puntuación. 1 = WebMCP detectado, 0 errores de esquema + 0 advertencias · 1 = detectado con problemas de esquema (errores o advertencias) · 0 = no detectado · error si la página de inicio no pudo escanearse.
Corrección. Añade una superficie de herramientas WebMCP. La forma declarativa es la única que un auditor externo puede verificar desde HTML estático: anota un `<form>` con `toolname` + `tooldescription`, y da a cada campo `name` + `toolparamdescription`. Corrige primero los errores de toolname ausente y de parámetro obligatorio sin name: son los fallos duros.
F3 · Servidor MCP anunciado (OAuth RFC 9728 / 8414)
un servidor MCP permite a los agentes llamar a tu API como herramientas gobernadas. F3 premia anunciar un endpoint MCP descubrible y protegido por OAuth mediante los metadatos estándar `.well-known`, para que un agente pueda autenticarse y conectarse sin una configuración a medida.
Puntuación. 3 = oauth-mcp completo (recurso protegido RFC 9728 + metadatos de servidor de autorización RFC 8414 + PKCE S256) · 2 = parcial · 1 = solo endpoint · 0 = ninguno · error si el sitio era inalcanzable.
Corrección. Sirve `/.well-known/oauth-protected-resource` apuntando a tu endpoint MCP y un documento de metadatos de servidor de autorización RFC 8414 en el mismo host que anuncie PKCE `S256`.
Por dónde empezar
En los 5.827 sitios del corpus público de AgentFit la puntuación mediana es de 22 sobre 100, una cuarta parte no llega a 11 y solo el 19 % supera 40. Los puntos se pierden en los mismos cuatro sitios, ordenados aquí por puntos disponibles por hora de trabajo:
- Sin /llms.txt en la raíz del host: el 75,0 % de los sitios saca cero en A1, que vale 3 puntos. Un fichero generado, un paso de build. El 57 % del corpus no tiene ni llms.txt, ni llms-full.txt, ni política para rastreadores de IA en robots.txt: ningún punto de entrada declarado para un agente.
- robots.txt no nombra ningún rastreador de IA ni incluye una línea Sitemap absoluta: el 65,8 % saca cero en A3, que vale 3 puntos. Cinco líneas de texto, en el fichero que todo rastreador lee primero.
- Sin compañero markdown para las páginas de documentación: el 77,9 % de los sitios donde la comprobación pudo ejecutarse saca cero en B1, que vale 5 puntos. La mayoría de los generadores de sitios estáticos ya tienen el markdown de origen; el trabajo está en el enrutado, no en escribir.
- Sin una especificación válida y descubrible: el 96,4 % saca cero en C1, que vale 8 puntos. La mayor pérdida individual del tablero y la única de las cuatro que es ingeniería de verdad y no configuración.
El orden importa más que la lista. Nueve criterios — llms.txt, llms-full.txt, robots, sitemap, etiquetas de descubrimiento en la portada, JSON-LD, canónica, fecha de modificación, taxonomías — suman 27 puntos y no exigen reescribir ni una línea de documentación; el sitio medio recoge 8,5 de esos 27, o sea que hay dieciocho puntos sobre la mesa. C1 y el catálogo de errores en D son semanas de trabajo y hay que planificarlos, no encajarlos a última hora. Una advertencia sobre la causalidad: los sitios con llms.txt tienen una mediana de 41 frente a 18 del resto, pero el fichero no regala 23 puntos. La flecha va más bien al revés: quien mantiene su documentación es quien añade el fichero. El marcado es una forma barata de sumar puntos, no una forma de hacer buena la documentación.
Todas las cifras de esta sección son una instantánea congelada: 5.827 hosts con una ejecución válida bajo la rúbrica v3, tomada el 27 de julio de 2026, una ejecución por host, sin los dominios que AgentFit posee. Los gráficos que hay más arriba en esta página se dibujan a partir del corpus vivo bajo la rúbrica ACTUAL, reponderada después de esa instantánea: no se espera que ambas series coincidan, y donde difieran, la medición vigente es la de los gráficos. Son URLs que la gente envió por su cuenta, no una lista curada de documentaciones de API, así que la mediana describe lo enviado y no el mercado.
Preguntas frecuentes
¿Qué es llms.txt y lo necesito de verdad?
Es un fichero Markdown en la raíz de tu host que indexa tu documentación: un título H1, encabezados de sección y enlaces a las páginas que importan, con el formato propuesto en llmstxt.org. Ningún rastreador está obligado a leerlo, y AgentFit no afirma que sea un estándar. Se puntúa porque cuesta un paso de build y es el único lugar donde eres tú, y no las heurísticas de un rastreador ajeno, quien decide qué cuenta como tu documentación. Su compañero /llms-full.txt es la misma idea llevada al texto completo.
¿Necesito un servidor MCP para sacar buena nota?
No. Toda la categoría de capacidad de agente son 4 puntos sobre 100: un sitio sin servidor MCP ni WebMCP puede pasar de 90. La categoría existe para registrar quién está construyendo superficies para agentes, no para castigar a quien no. Si tienes un servidor MCP, F3 comprueba que se anuncie como espera la especificación: metadatos de recurso protegido según la RFC 9728, documento de servidor de autorización según la RFC 8414 y PKCE con S256.
¿En qué se diferencia de Lighthouse o de una auditoría SEO?
En el lector. Lighthouse mide la experiencia de una persona en un navegador: tiempos de pintado, desplazamientos de diseño, accesibilidad de la página renderizada. Una auditoría SEO mide el encaje con un índice de búsqueda y sus señales de posicionamiento. AgentFit mide si un programa que no ejecuta tu JavaScript ni hace scroll puede obtener el contrato de tu API. El solape es real — renderizado sin JS, URLs canónicas y datos estructurados aparecen en las tres — pero los modos de fallo divergen, y una puntuación perfecta en Lighthouse es del todo compatible con una documentación que un agente no puede usar.
¿Por qué no hay un modelo de lenguaje en la puntuación?
Porque una puntuación que no puedes reproducir no es una medición. Cada comprobación es una petición HTTP más un analizador o una regla, así que el mismo sitio puntúa igual dos veces y cada punto lleva una URL y un fragmento que puedes verificar tú mismo. Dos clasificadores pequeños asisten a dos criterios; van compilados en el binario y versionados con él, de modo que el reentrenamiento de otro no mueve tu puntuación de la noche a la mañana. Las consecuencias prácticas: una auditoría completa tarda unos treinta segundos, no cuesta nada ejecutarla y la puede comprobar un escéptico.
¿Con qué frecuencia debo repetir la auditoría?
Tras cualquier cambio en cómo se construye o se sirve la documentación, y una vez al mes el resto del tiempo. Una puntuación solo se mueve cuando se mueve un hecho, así que las ejecuciones diarias miden sobre todo ruido de tu CDN. Compara dos ejecuciones en la vista de diferencias; si entre ellas cambió la versión de la rúbrica, la comparación se rechaza en lugar de mostrar nuestro cambio de vara de medir como una regresión tuya.
Mi puntuación es baja. ¿Qué me dice eso?
Normalmente no que la documentación sea mala para las personas. La forma más común de una puntuación baja es un sitio bien escrito servido como aplicación JavaScript y sin superficies para máquinas: el agente recibe una cáscara vacía, no hay gemelo markdown, no hay especificación, y todo lo demás cae detrás. Lee el informe empezando por la lista de arreglos: está ordenada por puntos por unidad de esfuerzo, y cada entrada nombra la URL que se descargó, así que puedes reproducir el hallazgo antes de planificar el trabajo.
¿Una puntuación alta hará que ChatGPT cite mi documentación?
Nadie puede prometerlo, y esta herramienta no lo hace. Lo que significa una puntuación alta es más estrecho y comprobable: un agente que llega a tu sitio puede obtenerlo, analizarlo y citarlo sin navegador. Que un motor de respuestas te cite depende además de la política de su rastreador, de con qué frecuencia se pregunta por tu producto y de una maquinaria de posicionamiento que ningún proveedor publica. AgentFit mide la parte que está bajo tu control.
¿Puedo aplicar la rúbrica yo mismo?
Sí, a mano. La especificación completa está en esta página, criterio a criterio; el mismo contenido se sirve como Markdown en esta URL con la cabecera Accept: text/markdown, y el esquema del informe está en el documento OpenAPI público. Lo que no puedes hacer es ejecutar nuestra implementación: el código es privado y no publicamos compilaciones. Lo que sí puedes hacer es pedirnos cuentas: /reproducibility publica tres informes en bruto y los comandos exactos para compararlos, campo a campo, con una ejecución en vivo del mismo sitio. Todos los sitios ya auditados se pueden consultar, así que puedes compararte con un competidor antes de empezar.
Audita tu documentación · Explora los sitios auditados · Comprueba un servidor MCP