How scoring works
Agent Rank weights and organizes checks into a tree. Some checks depend on others, so they only run if their parent check passes. For example, if your site has nollms.txt file, none of the checks that evaluate the contents of llms.txt run and you cannot get any points from them.
Focus on passing parent checks first to make the biggest improvements to how accessible your documentation is to agents.
| Category | What it checks | Weight |
|---|---|---|
| llms.txt | Does an /llms.txt file exist, follow the spec, and link to Markdown versions of pages? | 17 |
| llms-full.txt | Is there a bundled, well-structured corpus agents can ingest in one request? | 8 |
| skill.md | Does the site expose agent skills? | 8 |
| Markdown content negotiation | Can the server return clean markdown when an agent asks for it? | 10 |
| Plaintext content negotiation | Can the server return clean plaintext as a fallback? | 5 |
| MCP server | Is there a discoverable MCP server? Does it expose tools? | 20 |
| OpenAPI spec | Is there a machine-readable API specification at a standard path? | 12 |
| robots.txt allows AI agents | Does robots.txt allow AI crawlers? | 8 |
| Sitemap | Is there a discoverable, valid sitemap.xml? | 5 |
| Structured data | Does the homepage embed JSON-LD? | 4 |
| Response latency | Does the site respond in less than two seconds? | 3 |
llms.txt
This check fetches/llms.txt from your domain and fallback paths including /.well-known/llms.txt. The check passes if it can reach an llms.txt file with non-HTML text content.
Mintlify generates and hosts an llms.txt file for every documentation site. See llms.txt for customization options.
Why this check matters: llms.txt gives agents a standard starting point for discovering your documentation before crawling or guessing at navigation.
How to improve: If you use a reverse proxy, configure it to forward /llms.txt and /.well-known/llms.txt to your Mintlify subdomain. If you host your docs outside Mintlify, create an llms.txt file at the root of your site.
Create a valid llms.txt file for your documentation site.
llms.txt valid structure
The file must contain at least one Markdown link in[text](url) format.
Why this check matters: Without links, llms.txt cannot direct agents to your content.
How to improve: Mintlify-generated files always include links. If you use a custom file, ensure it contains links for each page using the [Page Title](url) format.
Ensure every documentation page is listed in your llms.txt as a Markdown link.
llms.txt size
Thellms.txt file must be under 100,000 characters. The check flags files over 50,000 characters as a truncation risk because agents don’t reliably process long files.
Why this check matters: Oversized files may be truncated by agents with limited context windows, causing them to miss pages listed toward the end.
How to improve: If you have a large custom llms.txt, trim it to the most important pages. Use llms-full.txt for the complete content corpus.
Reduce the size of your llms.txt file for agent compatibility.
llms.txt links resolve
This check samples up to 50 same-origin links. At least 90% must properly resolve and returnHTTP 200 status codes.
Why this check matters: Broken links mean agents cannot reach content.
How to improve: Mintlify-hosted llms.txt update each time you make a change to your site. For custom llms.txt files, audit links and fix renamed, moved, or deleted entries from your custom llms.txt.
Find and resolve broken links in llms.txt
llms.txt links point to Markdown
At least half of the links inllms.txt must end in .md.
Why this check matters: .md links let agents fetch the Markdown version of a page directly, which is more token-efficient than parsing HTML.
How to improve: Mintlify-generated llms.txt always uses .md links. If you have a custom file, append .md to your page URLs.
Ensure all documentation links in llms.txt point to Markdown source files (.md).
llms.txt directive format
The file must start with an H1 title like# Site name and include an H2 section heading like ## Docs or ## Documentation.
Why this check matters: This structure follows the llms.txt specification, which agents use to parse the file predictably.
How to improve: Mintlify-generated llms.txt files have these headings. For custom files, ensure the first non-empty line is an H1 like # Site name and the main page list appears under an H2 heading like ## Documentation.
Restructure your llms.txt to match the official format.
llms-full.txt
This check fetches/llms-full.txt from your domain and verifies it is reachable, returns a text content type, is non-empty, and is not HTML.
Mintlify automatically generates and hosts llms-full.txt for every documentation site. See llms.txt for details.
Why this check matters: A single-file corpus allows long-context agents to ingest your entire documentation in one pass without making individual page requests.
How to improve: Mintlify-generated llms-full.txt files update each time you make a change to your site. For custom llms-full.txt files, ensure the file is updated to include the full content of each page. If you use a reverse proxy, forward /llms-full.txt and /.well-known/llms-full.txt to your Mintlify subdomain.
Generate a compliant llms-full.txt file containing the full corpus of your documentation.
llms-full.txt size
Thellms-full.txt file must be between 500 and 5,000,000 characters.
Why this check matters: Files that are too small contain too little content to be useful. Files that are too large exceed what most agents can process in a single context window.
How to improve: If the file is too small, your site may have very few published pages. Start by adding more documentation content then update your llms-full.txt file. If the file is over the limit, identify less important information for agent context like changelog entries, info only relevant to humans like how to contact support, or other information that is not useful for agents. Also use llms.txt to point agents to individual pages.
Resize and optimize your llms-full.txt file to meet requirements.
llms-full.txt valid structure
Thellms-full.txt file must start with an H1 heading and contain at least two headings total.
Why this check matters: Structure helps agents navigate and chunk the file rather than processing it as undifferentiated text.
How to improve: Mintlify-generated files always meet this requirement. For custom files, ensure each major documentation section starts with a heading.
Insert required heading structure into your llms-full.txt file.
llms-full.txt links resolve
At least 90% of same-origin links in thellms-full.txt file must properly resolve and return an HTTP 200 status code.
Why this check matters: Broken links make content unreachable for agents following them. If an agent can’t follow a link, it may guess or fail to find content.
How to improve: Fix broken links in your documentation source then update your llms-full.txt file.
Find and fix broken links in your llms-full.txt file.
skill.md
This check looks for a skill discovery endpoint at/.well-known/agent-skills/index.json. If found, it fetches the first listed skill URL and verifies it returns Markdown content. If no index exists, it falls back to checking /skill.md directly.
Mintlify generates a skill.md file for every documentation site. See skill.md for customization options.
Why this check matters: While llms.txt tells agents where your content is, skill.md tells agents how to use your product. This gives agents the operating context they need to take meaningful actions on behalf of users.
How to improve: If you use a reverse proxy, configure it to forward /skill.md, /.well-known/skills/*, and /.well-known/agent-skills/* to your Mintlify subdomain.
Write a skill.md for your product.
Markdown content negotiation
This check sends a request to your documentation root withAccept: text/markdown, text/html;q=0.9 and verifies that the response Content-Type is text/markdown or text/x-markdown and the body is not HTML.
Mintlify handles this automatically for all hosted documentation sites.
Why this check matters: Agents requesting Markdown receive structured content that is more efficient to process than HTML. This reduces token usage and removes noise from navigation elements, scripts, and markup that takes up the context window.
How to improve: If you use a reverse proxy, ensure it forwards Accept headers to your Mintlify subdomain rather than stripping or overriding them.
Implement Markdown content negotiation for your documentation server.
Plaintext content negotiation
This check sends a request to your documentation root withAccept: text/plain, text/html;q=0.9 and verifies that the response returns a non-HTML text/* content type.
Mintlify handles this automatically for all hosted documentation sites.
Why this check matters: Some agents cannot handle Markdown and fall back to plain text. Support plain text fallback to keep your content accessible to simpler clients.
How to improve: If you use a reverse proxy, ensure it forwards Accept headers to your Mintlify subdomain.
Add plain text content negotiation to your documentation server.
MCP server
This check sends a JSON-RPCinitialize request to /mcp on your domain and verifies that the response includes a valid serverInfo.name.
Mintlify hosts an MCP server for every documentation site. See MCP server for details and configuration.
Why this check matters: An MCP server gives agents a way to integrate structured tools and typed outputs, rather than forcing them to scrape HTML or infer behavior from documentation.
How to improve: If you use a reverse proxy, configure it to forward /mcp to your Mintlify subdomain.
Expose an MCP server at /mcp on your documentation site.
Tool count
This check callstools/list and verifies at least one tool is returned.
Why this check matters: An MCP server with no tools offers no integrations for agents.
How to improve: If you use a reverse proxy, ensure it forwards requests to /mcp without stripping the request body or modifying headers that the MCP protocol depends on. If you host your own MCP server, implement the tools/list JSON-RPC method and register at least one tool with a valid name, description, and inputSchema.
Add tools to your MCP server so agents have an actionable integration surface.
OpenAPI specification
This check looks for a valid OpenAPI specification at standard paths:/openapi.json, /openapi.yaml, /swagger.json, /swagger.yaml, and /api/ variants of each. The specification must parse as valid JSON or YAML with an openapi or swagger version field.
Why this check matters: A discoverable OpenAPI specification gives agents context on your API surface, parameters, and schemas without scraping HTML. This is the most direct path for agents to call your API accurately.
How to improve: Host your OpenAPI specification at one of the standard paths listed above. If you already have a specification, verify it is publicly accessible without authentication.
Serve your OpenAPI specification at a standard path.
robots.txt
This check fetches/robots.txt and verifies that none of the known AI agent user-agents—including Claude, ChatGPT, Gemini, Copilot, and Perplexity—are blocked with Disallow: / or Disallow: /*. If no robots.txt exists, or it returns HTML, the check passes.
Why this check matters: Blocking AI crawlers in robots.txt prevents content from being indexed and fetched, even if your documentation is otherwise well-structured and publicly accessible.
How to improve: Review your robots.txt for blanket disallow rules targeting AI user-agents. Replace them with path-specific rules if you need to restrict access to certain sections without blocking all content.
Update robots.txt to allow AI agents.
Sitemap
This check fetches/sitemap.xml and verifies it returns a valid XML content type or starts with valid XML (<?xml, <urlset, or <sitemapindex).
Mintlify automatically generates and hosts a sitemap.xml for all documentation sites.
Why this check matters: A sitemap gives agents a complete URL inventory so they can plan systematic crawls without guessing at navigation or following every internal link.
How to improve: If you use a reverse proxy, forward /sitemap.xml to your Mintlify subdomain. If you host docs outside Mintlify, generate a sitemap with your static site generator or framework.
Generate a sitemap.xml for your documentation site.
Structured data
This check fetches your documentation homepage as HTML and looks for<script type="application/ld+json"> tags containing parseable JSON-LD.
Mintlify embeds JSON-LD structured data automatically in all page responses.
Why this check matters: JSON-LD gives agents machine-readable context about your pages-organization information, breadcrumbs, article metadata, and relationships—without requiring them to infer context from content or HTML structure.
How to improve: Mintlify handles this automatically. If you host docs outside Mintlify, add JSON-LD markup to your page templates.
Add JSON-LD structured data to your documentation site.
Response latency
This check times a GET request to your documentation root. It passes if the first byte arrives within 2,000 milliseconds and fails if the request times out. Why this check matters: Slow responses cause agent timeouts in multi-step workflows where documentation is fetched as a subtask. A two-second threshold accounts for agent processing overhead on top of network time. How to improve: If your site uses a reverse proxy or custom hosting, enable CDN caching, reduce server-side rendering time, and minimize blocking resources on the documentation homepage.Diagnose and fix slow documentation response time.