From 396d5c38943644a608650c29900ba7f37a292ee0 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 20 Apr 2026 14:47:34 -0700
Subject: [PATCH 01/15] create agent readiness checks page

---
 ai/agent-readiness-checks.mdx | 227 ++++++++++++++++++++++++++++++++++
 1 file changed, 227 insertions(+)
 create mode 100644 ai/agent-readiness-checks.mdx

diff --git a/ai/agent-readiness-checks.mdx b/ai/agent-readiness-checks.mdx
new file mode 100644
index 000000000..4b0634adb
--- /dev/null
+++ b/ai/agent-readiness-checks.mdx
@@ -0,0 +1,227 @@
+---
+title: "Agent readiness checks"
+description: "What each Agent Rank check tests, why it matters, and how to pass it."
+keywords: ["agent rank", "agent readiness", "llms.txt", "skill.md", "MCP", "robots.txt", "sitemap", "structured data", "content negotiation", "OpenAPI"]
+---
+
+[Agent Rank](https://agentrank.mintlify.com) scores your documentation site on how accessible it is to AI agents. This page explains what each agent readiness check tests, why it matters, and how to improve your documentation.
+
+## How scoring works
+
+Checks are weighted and organized into a tree. Some checks depend on other checks, so they only run if their parent check passes.
+
+For example, if your site has no `llms.txt` file, none of the checks that evaluate the contents of `llms.txt` run and you cannot get any points for them.
+
+Focus on passing parent checks first to make the biggest improvements to how accessible your documentation is to agents.
+
+## llms.txt
+
+The check fetches `/llms.txt` from your domain (and fallback paths including `/.well-known/llms.txt`). It passes if the file is reachable and returns a text content type with non-HTML content.
+
+Mintlify automatically generates and hosts `llms.txt` for every documentation site. See [llms.txt](/ai/llmstxt) for setup details and customization options.
+
+**Why it 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](/deploy/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.
+
+<Prompt description="Create a valid llms.txt" actions={["copy", "cursor"]}>
+Create a valid llms.txt file for my documentation site following the llmstxt.org specification. The file should start with a # heading for the site title, include a > blockquote description below the title, and list all main documentation pages under a ## Docs section. Each page entry should use Markdown link format pointing to the .md version of each URL: [Page Title](https://example.com/docs/page.md). Group pages by topic using ## section headings where appropriate.
+</Prompt>
+
+### llms.txt valid structure
+
+The file must contain at least one Markdown link in `[text](url)` format.
+
+**Why it 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 at least one `[Page Title](url)` entry.
+
+### llms.txt size
+
+The file must be under 100,000 characters. Files over 50,000 characters are flagged as a truncation risk.
+
+**Why it matters:** Oversized files may be truncated by AI tools with limited context windows, causing agents 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.
+
+### llms.txt links resolve
+
+Up to 50 same-origin links are sampled and checked. At least 90% must return HTTP 200.
+
+**Why it matters:** Broken links mean agents cannot reach content they were directed to.
+
+**How to improve:** Fix deleted or renamed pages, or remove outdated entries from your custom `llms.txt`.
+
+<Prompt description="Audit and fix broken links in llms.txt" actions={["copy", "cursor"]}>
+Review the links in my llms.txt file and identify any that may point to pages that no longer exist or have moved. For each broken link, suggest whether the page should be restored, the link updated to the new URL, or the entry removed from llms.txt.
+</Prompt>
+
+### llms.txt links point to Markdown
+
+At least 50% of links must end in `.md`.
+
+**Why it matters:** `.md` links let agents fetch the Markdown version of a page directly, which is cleaner and 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.
+
+### llms.txt directive format
+
+The file must start with an H1 title (`# Site Name`) and include a `## Docs` or `## Documentation` section heading.
+
+**Why it matters:** This structure follows the llms.txt specification, which tools use to parse the file predictably.
+
+**How to improve:** Mintlify-generated files always meet this requirement. For custom files, ensure the first non-empty line is an H1 and the main page list appears under a `## Docs` heading.
+
+## llms-full.txt
+
+The 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](/ai/llmstxt#llms-fulltxt) for details.
+
+**Why it matters:** A single-file corpus lets long-context agents ingest your entire documentation in one pass without making individual page requests.
+
+**How to improve:** If you use a reverse proxy, forward `/llms-full.txt` and `/.well-known/llms-full.txt` to your Mintlify subdomain.
+
+### llms-full.txt size
+
+The file must be between 500 and 5,000,000 characters.
+
+**Why it matters:** Files under 500 characters contain too little content to be useful. Files over 5MB exceed what most AI tools can process in a single context window.
+
+**How to improve:** If the file is too small, your site may have very few published pages—add more documentation content. If the file is over the limit, use `llms.txt` to point agents to individual pages instead.
+
+### llms-full.txt valid structure
+
+The file must start with an H1 heading and contain at least 2 headings total.
+
+**Why it 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.
+
+### llms-full.txt links resolve
+
+At least 90% of same-origin links in the file must return HTTP 200.
+
+**Why it matters:** Same reasoning as the `llms.txt` links resolve check—broken references make content unreachable to agents following them.
+
+**How to improve:** Fix broken links in your documentation source.
+
+## skill.md
+
+The 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 automatically generates a `skill.md` file for every documentation site. See [skill.md](/ai/skillmd) for setup details and customization options.
+
+**Why it matters:** While `llms.txt` tells agents where your content is, `skill.md` tells agents what your product does and how to use it. This gives AI assistants the operating context they need to take meaningful actions on behalf of users—not just find information.
+
+**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.
+
+<Prompt description="Write a skill.md for your product" actions={["copy", "cursor"]}>
+Write a skill.md file for my product following the agentskills.io specification. Start with YAML frontmatter containing name, description, license, and compatibility fields. Then document: Capabilities (high-level things agents can accomplish), Skills (specific actions with required inputs and constraints), and Workflows (step-by-step procedures for common tasks). Focus on what agents can do programmatically, not just what product features exist. Keep descriptions precise and action-oriented.
+</Prompt>
+
+## Markdown content negotiation
+
+The check sends a request to your documentation root with `Accept: 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 it matters:** Agents requesting Markdown receive clean, structured content without HTML overhead. This reduces token usage and removes noise from navigation elements, scripts, and markup.
+
+**How to improve:** If you use a [reverse proxy](/deploy/reverse-proxy), ensure it forwards `Accept` headers to your Mintlify subdomain rather than stripping or overriding them.
+
+<Prompt description="Add Markdown content negotiation to your server" actions={["copy", "cursor"]}>
+I need my documentation server to support HTTP content negotiation for Markdown. When a client sends Accept: text/markdown or Accept: text/x-markdown, the server should respond with the Markdown source of the page and set Content-Type: text/markdown. Show me how to configure this for [your server framework or platform].
+</Prompt>
+
+## Plaintext content negotiation
+
+The check sends a request to your documentation root with `Accept: 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 it matters:** Some agents and tools cannot handle Markdown and fall back to plain text. Supporting this keeps your content accessible to simpler clients.
+
+**How to improve:** Same as Markdown content negotiation—ensure your reverse proxy forwards `Accept` headers to Mintlify.
+
+## MCP server
+
+The check sends a JSON-RPC `initialize` request to `{yourDomain}/mcp` using the MCP protocol. It passes if the response includes a valid `serverInfo.name`.
+
+Mintlify hosts an MCP server for every documentation site. See [MCP server](/ai/model-context-protocol) for details and configuration.
+
+**Why it matters:** An MCP server gives agents a first-class integration path with 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.
+
+### Tool count
+
+After confirming the server is discoverable, the check calls `tools/list` and verifies at least one tool is returned.
+
+**Why it matters:** An MCP server with no tools offers no actionable integration surface for agents.
+
+**How to improve:** See [MCP resources](/ai/model-context-protocol#mcp-resources) to understand which tools Mintlify exposes and how to configure them.
+
+## OpenAPI spec
+
+The check looks for a valid spec at standard paths: `/openapi.json`, `/openapi.yaml`, `/swagger.json`, `/swagger.yaml`, and `/api/` variants of each. The spec must parse as valid JSON or YAML with an `openapi` or `swagger` version field.
+
+**Why it matters:** A discoverable OpenAPI spec lets agents auto-discover your API surface, parameters, and schemas without scraping documentation HTML. This is the most direct path for agents to call your API accurately.
+
+**How to improve:** Host your OpenAPI spec at one of the standard paths listed above. If you already have a spec, verify it is publicly accessible without authentication.
+
+<Prompt description="Serve your OpenAPI spec at a standard path" actions={["copy", "cursor"]}>
+I want to make my OpenAPI spec discoverable to AI agents at /openapi.json or /openapi.yaml. Show me how to configure my server to serve the spec file at that path with the correct Content-Type header (application/json for JSON, application/x-yaml for YAML). The spec should be publicly accessible without authentication.
+</Prompt>
+
+## robots.txt
+
+The 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 it 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.
+
+<Prompt description="Update robots.txt to allow AI agents" actions={["copy", "cursor"]}>
+Review my robots.txt and update it to allow the major AI agent crawlers: GPTBot, ClaudeBot, Claude-User, Google-Extended, PerplexityBot, Copilot, and OAI-SearchBot. Preserve any existing rules for non-AI bots. If I currently have a wildcard User-agent: * rule with Disallow: /, show me how to add explicit Allow rules for AI agents above it.
+</Prompt>
+
+## Sitemap
+
+The 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 it 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.
+
+<Prompt description="Generate a sitemap.xml for your docs site" actions={["copy", "cursor"]}>
+Generate a sitemap.xml for my documentation site. Include all public documentation pages with canonical URLs. Use the standard sitemap XML format with urlset, url, loc, and optionally lastmod and changefreq elements. The file should be served at /sitemap.xml with Content-Type: application/xml.
+</Prompt>
+
+## Structured data
+
+The 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 it 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.
+
+<Prompt description="Add JSON-LD structured data to your documentation" actions={["copy", "cursor"]}>
+Add JSON-LD structured data to my documentation site. Include a WebSite schema on the homepage and a TechArticle or Article schema on individual documentation pages. Add BreadcrumbList markup for page hierarchy and Organization markup for the company. Show me where to place the `<script type="application/ld+json">` tag in my HTML template and what properties to include for a technical documentation site.
+</Prompt>
+
+## Response latency
+
+The check times a direct request to your documentation root and passes if the first byte arrives within 2,000 milliseconds. The check fails if the request times out.
+
+**Why it matters:** Slow responses cause agent timeouts in multi-step workflows where documentation is fetched as a subtask. A 2-second threshold accounts for agent processing overhead on top of network time.
+
+**How to improve:** For Mintlify-hosted sites, response time is handled by Mintlify's infrastructure and should pass for most deployments. 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.
+
+<Prompt description="Diagnose slow documentation response time" actions={["copy", "cursor"]}>
+My documentation site is responding slowly (over 2 seconds to first byte). Help me identify the cause. Analyze: server-side rendering time, missing CDN or cache headers, unoptimized assets, third-party scripts blocking page load, and uncached database queries. Suggest specific changes to bring time-to-first-byte under 2 seconds. My site is hosted on [your hosting platform].
+</Prompt>

From 19a7f4df8f115c496448118815159c4517ed7ab4 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 20 Apr 2026 14:47:43 -0700
Subject: [PATCH 02/15] update nav

---
 docs.json | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs.json b/docs.json
index bf1ac4aec..31b821d3a 100644
--- a/docs.json
+++ b/docs.json
@@ -214,15 +214,15 @@
                       "assistant/use"
                     ]
                   },
+                  "ai/agent-readiness-checks",
                   "ai/contextual-menu",
-                  "optimize/analytics",
-                  "optimize/feedback",
                   "ai/llmstxt",
                   "ai/skillmd",
                   "ai/model-context-protocol",
-                  "optimize/seo",
                   "ai/markdown-export",
-                  "optimize/pdf-exports",
+                  "optimize/analytics",
+                  "optimize/feedback",
+                  "optimize/seo",
                   {
                     "group": "Integrations",
                     "pages": [
@@ -271,7 +271,8 @@
                         ]
                       }
                     ]
-                  }
+                  },
+                  "optimize/pdf-exports"
                 ]
               }
             ]

From 8f084517e33fd116883c38e5cd2e77a7cb587999 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 20 Apr 2026 15:08:47 -0700
Subject: [PATCH 03/15] update intro

---
 ai/agent-readiness-checks.mdx | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/ai/agent-readiness-checks.mdx b/ai/agent-readiness-checks.mdx
index 4b0634adb..272648c3d 100644
--- a/ai/agent-readiness-checks.mdx
+++ b/ai/agent-readiness-checks.mdx
@@ -1,26 +1,32 @@
 ---
 title: "Agent readiness checks"
-description: "What each Agent Rank check tests, why it matters, and how to pass it."
-keywords: ["agent rank", "agent readiness", "llms.txt", "skill.md", "MCP", "robots.txt", "sitemap", "structured data", "content negotiation", "OpenAPI"]
+description: "What each Agent Rank check tests, why it matters, and how to make your documentation more agent friendly."
+keywords: ["agent rank", "agent friendly"]
 ---
 
-[Agent Rank](https://agentrank.mintlify.com) scores your documentation site on how accessible it is to AI agents. This page explains what each agent readiness check tests, why it matters, and how to improve your documentation.
+[Agent Rank](https://agentrank.mintlify.com) scores your documentation site on how accessible it is to AI agents. This page explains what each agent readiness check tests, why it matters, and how to make your documentation more agent friendly.
 
 ## How scoring works
 
-Checks are weighted and organized into a tree. Some checks depend on other checks, so they only run if their parent check passes.
+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 no `llms.txt` file, none of the checks that evaluate the contents of `llms.txt` run and you cannot get any points for them.
+For example, if your site has no `llms.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.
 
+<Tip>
+  Every check includes a ready-to-use prompt for improving your documentation and passing the check and any dependent checks.
+
+  Click **Copy prompt** and paste it into your preferred tool to make your documentation more accessible to agents.
+</Tip>
+
 ## llms.txt
 
-The check fetches `/llms.txt` from your domain (and fallback paths including `/.well-known/llms.txt`). It passes if the file is reachable and returns a text content type with non-HTML content.
+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 automatically generates and hosts `llms.txt` for every documentation site. See [llms.txt](/ai/llmstxt) for setup details and customization options.
+Mintlify generates and hosts an `llms.txt` file for every documentation site. See [llms.txt](/ai/llmstxt) for customization options.
 
-**Why it matters:** `llms.txt` gives agents a standard starting point for discovering your documentation before crawling or guessing at navigation.
+**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](/deploy/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.
 

From 4d9e3194497cb2d663c007c09854e6133bd1007d Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 20 Apr 2026 15:14:27 -0700
Subject: [PATCH 04/15] optimize prompt

---
 ai/agent-readiness-checks.mdx | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/ai/agent-readiness-checks.mdx b/ai/agent-readiness-checks.mdx
index 272648c3d..aca0a94e9 100644
--- a/ai/agent-readiness-checks.mdx
+++ b/ai/agent-readiness-checks.mdx
@@ -30,8 +30,19 @@ Mintlify generates and hosts an `llms.txt` file for every documentation site. Se
 
 **How to improve:** If you use a [reverse proxy](/deploy/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.
 
-<Prompt description="Create a valid llms.txt" actions={["copy", "cursor"]}>
-Create a valid llms.txt file for my documentation site following the llmstxt.org specification. The file should start with a # heading for the site title, include a > blockquote description below the title, and list all main documentation pages under a ## Docs section. Each page entry should use Markdown link format pointing to the .md version of each URL: [Page Title](https://example.com/docs/page.md). Group pages by topic using ## section headings where appropriate.
+<Prompt description="Create a fully-compliant `llms.txt` file for your documentation site" actions={["copy", "cursor"]}>
+Generate an `llms.txt` file for my documentation site that fully adheres to the [llms.txt format specification](https://llmstxt.org#format). 
+
+Requirements:
+- The file must begin with a `#` heading containing the site title.
+- Immediately below the title, add a blockquote (`>`) with a concise site description.
+- For navigation, include one or more `##` section headers that match the site's main navigation structure.
+- Under each section, list every documentation page as a Markdown link to its `.md` version immediately followed by a short description of the page content ([Page Title](https://example.com/docs/page.md): Description of the page contents).
+- Ensure page list and hierarchy accurately reflect the docs site's structure.
+- Use clear, specific, human-readable descriptions for each page.
+- Output only the content of the `llms.txt` file—do not provide explanations or commentary.
+
+This file should be ready to serve at the site root, be valid plain text, and follow all required structural and formatting conventions.
 </Prompt>
 
 ### llms.txt valid structure

From 151d6c64cf41d691f70a2aeba296d2d5ae16fd32 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 20 Apr 2026 16:08:14 -0700
Subject: [PATCH 05/15] add prompts

---
 ai/agent-readiness-checks.mdx | 120 +++++++++++++++++++++++++++-------
 1 file changed, 98 insertions(+), 22 deletions(-)

diff --git a/ai/agent-readiness-checks.mdx b/ai/agent-readiness-checks.mdx
index aca0a94e9..46c3b68df 100644
--- a/ai/agent-readiness-checks.mdx
+++ b/ai/agent-readiness-checks.mdx
@@ -30,7 +30,7 @@ Mintlify generates and hosts an `llms.txt` file for every documentation site. Se
 
 **How to improve:** If you use a [reverse proxy](/deploy/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.
 
-<Prompt description="Create a fully-compliant `llms.txt` file for your documentation site" actions={["copy", "cursor"]}>
+<Prompt description="Create a valid `llms.txt` file for your documentation site." actions={["copy", "cursor"]}>
 Generate an `llms.txt` file for my documentation site that fully adheres to the [llms.txt format specification](https://llmstxt.org#format). 
 
 Requirements:
@@ -49,23 +49,35 @@ This file should be ready to serve at the site root, be valid plain text, and fo
 
 The file must contain at least one Markdown link in `[text](url)` format.
 
-**Why it matters:** Without links, `llms.txt` cannot direct agents to your content.
+**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 at least one `[Page Title](url)` entry.
+**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.
+
+<Prompt description="Add links to your `llms.txt` file." actions={["copy", "cursor"]}>
+Add any missing `[Page Title](url)`-style Markdown links to my llms.txt file, one for each documentation page. Each link should point to the corresponding `.md` page and use clear, human-readable titles. If my `llms.txt` file is missing links for some pages, add them in the correct section according to the [llms.txt format specification](https://llmstxt.org#format).
+</Prompt>
 
 ### llms.txt size
 
-The file must be under 100,000 characters. Files over 50,000 characters are flagged as a truncation risk.
+The `llms.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 it matters:** Oversized files may be truncated by AI tools with limited context windows, causing agents to miss pages listed toward the end.
+**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.
 
+<Prompt description="Trim your `llms.txt` file to a safe size." actions={["copy", "cursor"]}>
+My `llms.txt` file is too large and risks being truncated by agents with limited context windows. Review it and suggest which entries to remove or move to `llms-full.txt` to bring the file under 50,000 characters.
+
+Prioritize keeping: top-level overview pages, getting started guides, API reference index pages, and entry points to major sections. Remove or consolidate: deeply nested sub-pages, pages with highly similar content, and changelog or release note entries.
+
+Output a revised `llms.txt` that stays under 50,000 characters while preserving the most discoverable content.
+</Prompt>
+
 ### llms.txt links resolve
 
 Up to 50 same-origin links are sampled and checked. At least 90% must return HTTP 200.
 
-**Why it matters:** Broken links mean agents cannot reach content they were directed to.
+**Why this check matters:** Broken links mean agents cannot reach content they were directed to.
 
 **How to improve:** Fix deleted or renamed pages, or remove outdated entries from your custom `llms.txt`.
 
@@ -77,25 +89,38 @@ Review the links in my llms.txt file and identify any that may point to pages th
 
 At least 50% of links must end in `.md`.
 
-**Why it matters:** `.md` links let agents fetch the Markdown version of a page directly, which is cleaner and more token-efficient than parsing HTML.
+**Why this check matters:** `.md` links let agents fetch the Markdown version of a page directly, which is cleaner and 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.
 
+<Prompt description="Convert links in your `llms.txt` to point to Markdown files." actions={["copy", "cursor"]}>
+My `llms.txt` file contains links that don't end in `.md`. Update every link to point to the Markdown version of the page—for example, change `https://example.com/docs/page` to `https://example.com/docs/page.md`. Leave links that already end in `.md` unchanged. Output the complete updated `llms.txt`.
+</Prompt>
+
 ### llms.txt directive format
 
 The file must start with an H1 title (`# Site Name`) and include a `## Docs` or `## Documentation` section heading.
 
-**Why it matters:** This structure follows the llms.txt specification, which tools use to parse the file predictably.
+**Why this check matters:** This structure follows the llms.txt specification, which tools use to parse the file predictably.
 
 **How to improve:** Mintlify-generated files always meet this requirement. For custom files, ensure the first non-empty line is an H1 and the main page list appears under a `## Docs` heading.
 
+<Prompt description="Fix the structure of your `llms.txt` to follow the specification." actions={["copy", "cursor"]}>
+My `llms.txt` file doesn't follow the required [llms.txt format](https://llmstxt.org#format). Fix it so that:
+- The first non-empty line is an H1 heading with the site name: `# Site Name`
+- A blockquote description follows immediately: `> Brief description of the site`
+- All page links appear under a `## Docs` section heading
+
+Preserve all existing links and titles. Only restructure the file to meet the specification. Output the complete corrected `llms.txt`.
+</Prompt>
+
 ## llms-full.txt
 
 The 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](/ai/llmstxt#llms-fulltxt) for details.
 
-**Why it matters:** A single-file corpus lets long-context agents ingest your entire documentation in one pass without making individual page requests.
+**Why this check matters:** A single-file corpus lets long-context agents ingest your entire documentation in one pass without making individual page requests.
 
 **How to improve:** If you use a reverse proxy, forward `/llms-full.txt` and `/.well-known/llms-full.txt` to your Mintlify subdomain.
 
@@ -103,33 +128,61 @@ Mintlify automatically generates and hosts `llms-full.txt` for every documentati
 
 The file must be between 500 and 5,000,000 characters.
 
-**Why it matters:** Files under 500 characters contain too little content to be useful. Files over 5MB exceed what most AI tools can process in a single context window.
+**Why this check matters:** Files under 500 characters contain too little content to be useful. Files over 5MB exceed what most AI tools can process in a single context window.
 
 **How to improve:** If the file is too small, your site may have very few published pages—add more documentation content. If the file is over the limit, use `llms.txt` to point agents to individual pages instead.
 
+<Prompt description="Fix the size of your `llms-full.txt` file." actions={["copy", "cursor"]}>
+My `llms-full.txt` file is outside the required size range (500–5,000,000 characters).
+
+If it's too small: Review my documentation and add the full Markdown content of any missing pages, with each page separated by a `###` heading matching the page title.
+
+If it's too large: Identify the least essential content—verbose changelogs, auto-generated reference pages, or near-duplicate sections—and suggest what to remove or summarize to bring the file under 5,000,000 characters.
+
+Output a revised `llms-full.txt` within the valid range.
+</Prompt>
+
 ### llms-full.txt valid structure
 
 The file must start with an H1 heading and contain at least 2 headings total.
 
-**Why it matters:** Structure helps agents navigate and chunk the file rather than processing it as undifferentiated text.
+**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.
 
+<Prompt description="Add heading structure to your `llms-full.txt` file." actions={["copy", "cursor"]}>
+My `llms-full.txt` file is missing the required heading structure—it must start with an H1 and contain at least 2 headings. Restructure it so that:
+- The first line is an H1 with the site name: `# Site Name`
+- Each major documentation section starts with a `##` heading
+- Individual pages within each section use `###` headings
+
+Preserve all existing content. Only add structure through headings. Output the complete restructured file.
+</Prompt>
+
 ### llms-full.txt links resolve
 
 At least 90% of same-origin links in the file must return HTTP 200.
 
-**Why it matters:** Same reasoning as the `llms.txt` links resolve check—broken references make content unreachable to agents following them.
+**Why this check matters:** Same reasoning as the `llms.txt` links resolve check—broken references make content unreachable to agents following them.
 
 **How to improve:** Fix broken links in your documentation source.
 
+<Prompt description="Find and fix broken links in your `llms-full.txt` file." actions={["copy", "cursor"]}>
+My `llms-full.txt` file contains links that don't resolve. Review the links in the file and for each broken one:
+1. If the page moved, update the link to the new URL
+2. If the page was removed, delete the link and its surrounding content from the corpus
+3. If the URL format is wrong (missing `.md`, incorrect path prefix), fix it
+
+Output the corrected `llms-full.txt` with all broken links resolved or removed.
+</Prompt>
+
 ## skill.md
 
 The 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 automatically generates a `skill.md` file for every documentation site. See [skill.md](/ai/skillmd) for setup details and customization options.
 
-**Why it matters:** While `llms.txt` tells agents where your content is, `skill.md` tells agents what your product does and how to use it. This gives AI assistants the operating context they need to take meaningful actions on behalf of users—not just find information.
+**Why this check matters:** While `llms.txt` tells agents where your content is, `skill.md` tells agents what your product does and how to use it. This gives AI assistants the operating context they need to take meaningful actions on behalf of users—not just find information.
 
 **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.
 
@@ -143,7 +196,7 @@ The check sends a request to your documentation root with `Accept: text/markdown
 
 Mintlify handles this automatically for all hosted documentation sites.
 
-**Why it matters:** Agents requesting Markdown receive clean, structured content without HTML overhead. This reduces token usage and removes noise from navigation elements, scripts, and markup.
+**Why this check matters:** Agents requesting Markdown receive clean, structured content without HTML overhead. This reduces token usage and removes noise from navigation elements, scripts, and markup.
 
 **How to improve:** If you use a [reverse proxy](/deploy/reverse-proxy), ensure it forwards `Accept` headers to your Mintlify subdomain rather than stripping or overriding them.
 
@@ -157,33 +210,56 @@ The check sends a request to your documentation root with `Accept: text/plain, t
 
 Mintlify handles this automatically for all hosted documentation sites.
 
-**Why it matters:** Some agents and tools cannot handle Markdown and fall back to plain text. Supporting this keeps your content accessible to simpler clients.
+**Why this check matters:** Some agents and tools cannot handle Markdown and fall back to plain text. Supporting this keeps your content accessible to simpler clients.
 
 **How to improve:** Same as Markdown content negotiation—ensure your reverse proxy forwards `Accept` headers to Mintlify.
 
+<Prompt description="Add plain text content negotiation to your documentation server." actions={["copy", "cursor"]}>
+My documentation server needs to return plain text when a client sends `Accept: text/plain`. Configure it so that requests with `Accept: text/plain` return `Content-Type: text/plain` with a non-HTML body. Preserve normal HTML responses for browser requests. Show me the configuration for [your server platform or framework].
+</Prompt>
+
 ## MCP server
 
 The check sends a JSON-RPC `initialize` request to `{yourDomain}/mcp` using the MCP protocol. It passes if the response includes a valid `serverInfo.name`.
 
 Mintlify hosts an MCP server for every documentation site. See [MCP server](/ai/model-context-protocol) for details and configuration.
 
-**Why it matters:** An MCP server gives agents a first-class integration path with structured tools and typed outputs, rather than forcing them to scrape HTML or infer behavior from documentation.
+**Why this check matters:** An MCP server gives agents a first-class integration path with 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.
 
+<Prompt description="Expose an MCP server at `/mcp` on your documentation site." actions={["copy", "cursor"]}>
+I need to expose an MCP (Model Context Protocol) server at `/mcp` so AI agents can discover and call tools on my documentation site. My site is hosted on [your platform].
+
+Show me how to:
+1. Set up an endpoint at `/mcp` that responds to JSON-RPC `initialize` requests with a valid `serverInfo` object containing a `name` field
+2. Handle the `tools/list` JSON-RPC method to return at least one tool definition
+3. Forward `/mcp` through my reverse proxy if one is in use
+</Prompt>
+
 ### Tool count
 
 After confirming the server is discoverable, the check calls `tools/list` and verifies at least one tool is returned.
 
-**Why it matters:** An MCP server with no tools offers no actionable integration surface for agents.
+**Why this check matters:** An MCP server with no tools offers no actionable integration surface for agents.
 
 **How to improve:** See [MCP resources](/ai/model-context-protocol#mcp-resources) to understand which tools Mintlify exposes and how to configure them.
 
+<Prompt description="Add tools to your MCP server so agents have an actionable integration surface." actions={["copy", "cursor"]}>
+My MCP server at `/mcp` is reachable but returns no tools from `tools/list`. Add at least one tool so agents can take meaningful actions. For a documentation site, useful tools include:
+
+- `search_docs`: Search documentation by query and return matching page excerpts
+- `get_page`: Fetch a specific page by URL or slug and return its Markdown content
+- `list_sections`: Return the top-level navigation structure
+
+Implement and register at least one of these so `tools/list` returns a valid tool definition with `name`, `description`, and `inputSchema`.
+</Prompt>
+
 ## OpenAPI spec
 
 The check looks for a valid spec at standard paths: `/openapi.json`, `/openapi.yaml`, `/swagger.json`, `/swagger.yaml`, and `/api/` variants of each. The spec must parse as valid JSON or YAML with an `openapi` or `swagger` version field.
 
-**Why it matters:** A discoverable OpenAPI spec lets agents auto-discover your API surface, parameters, and schemas without scraping documentation HTML. This is the most direct path for agents to call your API accurately.
+**Why this check matters:** A discoverable OpenAPI spec lets agents auto-discover your API surface, parameters, and schemas without scraping documentation HTML. This is the most direct path for agents to call your API accurately.
 
 **How to improve:** Host your OpenAPI spec at one of the standard paths listed above. If you already have a spec, verify it is publicly accessible without authentication.
 
@@ -195,7 +271,7 @@ I want to make my OpenAPI spec discoverable to AI agents at /openapi.json or /op
 
 The 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 it 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.
+**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.
 
@@ -209,7 +285,7 @@ The check fetches `/sitemap.xml` and verifies it returns a valid XML content typ
 
 Mintlify automatically generates and hosts a `sitemap.xml` for all documentation sites.
 
-**Why it matters:** A sitemap gives agents a complete URL inventory so they can plan systematic crawls without guessing at navigation or following every internal link.
+**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.
 
@@ -223,7 +299,7 @@ The check fetches your documentation homepage as HTML and looks for `<script typ
 
 Mintlify embeds JSON-LD structured data automatically in all page responses.
 
-**Why it 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.
+**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.
 
@@ -235,7 +311,7 @@ Add JSON-LD structured data to my documentation site. Include a WebSite schema o
 
 The check times a direct request to your documentation root and passes if the first byte arrives within 2,000 milliseconds. The check fails if the request times out.
 
-**Why it matters:** Slow responses cause agent timeouts in multi-step workflows where documentation is fetched as a subtask. A 2-second threshold accounts for agent processing overhead on top of network time.
+**Why this check matters:** Slow responses cause agent timeouts in multi-step workflows where documentation is fetched as a subtask. A 2-second threshold accounts for agent processing overhead on top of network time.
 
 **How to improve:** For Mintlify-hosted sites, response time is handled by Mintlify's infrastructure and should pass for most deployments. 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.
 

From a6120813f34ab4a75c7f636c8b1a38204bf029cd Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 20 Apr 2026 16:21:58 -0700
Subject: [PATCH 06/15] update prompts

---
 ai/agent-readiness-checks.mdx | 31 ++++++++++++++++++++-----------
 1 file changed, 20 insertions(+), 11 deletions(-)

diff --git a/ai/agent-readiness-checks.mdx b/ai/agent-readiness-checks.mdx
index 46c3b68df..33d8c1040 100644
--- a/ai/agent-readiness-checks.mdx
+++ b/ai/agent-readiness-checks.mdx
@@ -53,8 +53,8 @@ The file must contain at least one Markdown link in `[text](url)` format.
 
 **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.
 
-<Prompt description="Add links to your `llms.txt` file." actions={["copy", "cursor"]}>
-Add any missing `[Page Title](url)`-style Markdown links to my llms.txt file, one for each documentation page. Each link should point to the corresponding `.md` page and use clear, human-readable titles. If my `llms.txt` file is missing links for some pages, add them in the correct section according to the [llms.txt format specification](https://llmstxt.org#format).
+<Prompt description="Ensure every documentation page is listed in your `llms.txt` as a Markdown link." actions={["copy", "cursor"]}>
+Review my llms.txt file and add a `[Page Title](url): Description of the page contents` style Markdown link for every documentation page that is missing. Each link must point to the `.md` version of the page, use a clear, human-readable title, and include a concise description of the page content. Make sure no documentation page is omitted, and that the format matches the llms.txt specification exactly.
 </Prompt>
 
 ### llms.txt size
@@ -65,24 +65,33 @@ The `llms.txt` file must be under 100,000 characters. The check flags files over
 
 **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.
 
-<Prompt description="Trim your `llms.txt` file to a safe size." actions={["copy", "cursor"]}>
-My `llms.txt` file is too large and risks being truncated by agents with limited context windows. Review it and suggest which entries to remove or move to `llms-full.txt` to bring the file under 50,000 characters.
+<Prompt description="Reduce the size of your `llms.txt` file for agent compatibility." actions={["copy", "cursor"]}>
+Review my `llms.txt` file if it exceeds 50,000 characters and optimize it to be well under this threshold. 
 
-Prioritize keeping: top-level overview pages, getting started guides, API reference index pages, and entry points to major sections. Remove or consolidate: deeply nested sub-pages, pages with highly similar content, and changelog or release note entries.
+Prioritize keeping:
+- High-level overview pages
+- Onboarding and "get started" docs
+- API reference index and section entry points
+- Pages that are essential for agents to understand site structure
 
-Output a revised `llms.txt` that stays under 50,000 characters while preserving the most discoverable content.
+Consider removing or moving to a final `## Optional` section:
+- Deeply nested and less-visited sub-pages
+- Pages with redundant or highly similar content
+- Changelog, release notes, or historical archives
+
+Return a revised, specification-compliant `llms.txt` that maintains coverage of the most important and frequently referenced content, structured for clarity and optimal agent ingestion.
 </Prompt>
 
 ### llms.txt links resolve
 
-Up to 50 same-origin links are sampled and checked. At least 90% must return HTTP 200.
+This check samples up to 50 same-origin links. At least 90% must properly resolve and return `HTTP 200` status codes.
 
-**Why this check matters:** Broken links mean agents cannot reach content they were directed to.
+**Why this check matters:** Broken links mean agents cannot reach content.
 
-**How to improve:** Fix deleted or renamed pages, or remove outdated entries from your custom `llms.txt`.
+**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`.
 
-<Prompt description="Audit and fix broken links in llms.txt" actions={["copy", "cursor"]}>
-Review the links in my llms.txt file and identify any that may point to pages that no longer exist or have moved. For each broken link, suggest whether the page should be restored, the link updated to the new URL, or the entry removed from llms.txt.
+<Prompt description="Find and resolve broken links in llms.txt" actions={["copy", "cursor"]}>
+Audit all links in my llms.txt file to find any that lead to missing or relocated pages. For each broken or outdated link you find, recommend the best action: update the link to the correct URL if the page has moved, restore the missing page if it should exist, or remove the entry if it is obsolete. Summarize your findings and provide the exact changes required to keep llms.txt accurate and up to date.
 </Prompt>
 
 ### llms.txt links point to Markdown

From c7bbe7e521a3c6caa31a5446ca5637956d32a5bc Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 20 Apr 2026 16:39:44 -0700
Subject: [PATCH 07/15] update prompts

---
 ai/agent-readiness-checks.mdx | 241 ++++++++++++++++++++++++++--------
 1 file changed, 189 insertions(+), 52 deletions(-)

diff --git a/ai/agent-readiness-checks.mdx b/ai/agent-readiness-checks.mdx
index 33d8c1040..783a6657e 100644
--- a/ai/agent-readiness-checks.mdx
+++ b/ai/agent-readiness-checks.mdx
@@ -96,59 +96,113 @@ Audit all links in my llms.txt file to find any that lead to missing or relocate
 
 ### llms.txt links point to Markdown
 
-At least 50% of links must end in `.md`.
+At least half of the links in `llms.txt` must end in `.md`.
 
-**Why this check matters:** `.md` links let agents fetch the Markdown version of a page directly, which is cleaner and more token-efficient than parsing HTML.
+**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.
 
-<Prompt description="Convert links in your `llms.txt` to point to Markdown files." actions={["copy", "cursor"]}>
-My `llms.txt` file contains links that don't end in `.md`. Update every link to point to the Markdown version of the page—for example, change `https://example.com/docs/page` to `https://example.com/docs/page.md`. Leave links that already end in `.md` unchanged. Output the complete updated `llms.txt`.
+<Prompt description="Ensure all documentation links in `llms.txt` point to Markdown source files (.md)." actions={["copy", "cursor"]}>
+Review the provided `llms.txt` for documentation links.
+
+**Objective:** Every link to documentation content should end with `.md` (the raw Markdown source), unless the destination is intentionally non-Markdown (e.g., an external site, API endpoint, or other non-doc resource).
+
+**Instructions:**
+- For each documentation link that does not end in `.md`, update the URL to point to the corresponding `.md` file—typically by inserting `.md` before any query string or fragment, while avoiding double slashes.
+- Do not alter links that already end with `.md`.
+- Do not modify the visible link text, list structure, or any section headings.
+- For any link that cannot be safely rewritten (e.g., its target is ambiguous, external, or requires human judgment), add it to a clearly marked “Needs review” section, and briefly state why.
+
+After making these changes, provide:
+1. The full revised `llms.txt` file.
+2. A concise summary with:
+    - Total number of links processed
+    - The count (and percentage) that now end with `.md`
+    - A list of any links that require manual review.
+
 </Prompt>
 
 ### llms.txt directive format
 
-The file must start with an H1 title (`# Site Name`) and include a `## Docs` or `## Documentation` section heading.
+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`.
 
-**Why this check matters:** This structure follows the llms.txt specification, which tools use to parse the file predictably.
+<Prompt description="Restructure your `llms.txt` to match the official format." actions={["copy", "cursor"]}>
+My `llms.txt` file does not comply with the required [llms.txt format](https://llmstxt.org#format). Please rewrite it so that:
 
-**How to improve:** Mintlify-generated files always meet this requirement. For custom files, ensure the first non-empty line is an H1 and the main page list appears under a `## Docs` heading.
+1. The first non-empty line is an H1 heading with the exact site name in the form: `# Site Name`
+2. The H1 is immediately followed by a single blockquote line summarizing the site, like: `> Brief description of the site`
+3. All documentation links are grouped under an H2 section titled `## Documentation`
 
-<Prompt description="Fix the structure of your `llms.txt` to follow the specification." actions={["copy", "cursor"]}>
-My `llms.txt` file doesn't follow the required [llms.txt format](https://llmstxt.org#format). Fix it so that:
-- The first non-empty line is an H1 heading with the site name: `# Site Name`
-- A blockquote description follows immediately: `> Brief description of the site`
-- All page links appear under a `## Docs` section heading
+**Instructions:**
+- Keep all existing page links, titles, and content—just reorganize them into the correct heading and section structure.
+- Do not edit link URLs or titles.
+- Do not add or remove any links or content besides required headings.
+- If any required section (H1, blockquote, `## Docs`) is missing, add it in the appropriate place.
+- Ensure there is exactly one H1 at the top, followed by a blockquote, then the `## Docs` section with all page links directly beneath.
 
-Preserve all existing links and titles. Only restructure the file to meet the specification. Output the complete corrected `llms.txt`.
+Output only the full, fixed `llms.txt` file that passes the format requirements.
 </Prompt>
 
 ## llms-full.txt
 
-The 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.
+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](/ai/llmstxt#llms-fulltxt) for details.
 
-**Why this check matters:** A single-file corpus lets long-context agents ingest your entire documentation in one pass without making individual page requests.
+**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.
+
+<Prompt description="Generate a compliant `llms-full.txt` file containing the full corpus of your documentation." actions={["copy", "cursor"]}>
+You have access to my entire documentation source (MDX/Markdown files). Generate a `llms-full.txt` file that:
+
+1. Starts with an H1 heading with the exact site name (from my `docs.json`), with no extra text.
+2. Includes a blockquote with a concise, plain-language description of the site. Use the `description` field from my `docs.json` if present. Otherwise, generate a concise description of the site.
+3. Is followed by the **full content** of every public documentation page that should be in the agent corpus.
+    - Each page's content should be preceded by a top-level heading (`###`) that matches the page title.
+    - If available, include frontmatter `title` and `description` as part of each section.
+4. Has a total length between 500 and 5,000,000 characters.
+5. Does **not** include duplicate pages, boilerplate, or irrelevant internal/experimental content.
+6. Contains at least two Markdown headings overall, including the initial H1.
+
+**Instructions:**
+- Source only content from the current published documentation and linked pages.
+- Ensure Markdown is original and clean—do not pad with meaningless text.
+- Only include Markdown. There should be no HTML, JS, or other non-Markdown content.
+- Separate each page's content cleanly with `###` headings for navigation.
+- The file should be suitable for direct upload and ingestion by LLMs.
+
+When done, report the character count and confirm it is within the 500-5,000,000 character requirement.
+</Prompt>
 
-**How to improve:** If you use a reverse proxy, forward `/llms-full.txt` and `/.well-known/llms-full.txt` to your Mintlify subdomain.
 
 ### llms-full.txt size
 
-The file must be between 500 and 5,000,000 characters.
+The `llms-full.txt` file must be between 500 and 5,000,000 characters.
 
-**Why this check matters:** Files under 500 characters contain too little content to be useful. Files over 5MB exceed what most AI tools can process in a single context window.
+**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—add more documentation content. If the file is over the limit, use `llms.txt` to point agents to individual pages instead.
+**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.
 
-<Prompt description="Fix the size of your `llms-full.txt` file." actions={["copy", "cursor"]}>
-My `llms-full.txt` file is outside the required size range (500–5,000,000 characters).
+<Prompt description="Resize and optimize your `llms-full.txt` file to meet requirements." actions={["copy", "cursor"]}>
+The `llms-full.txt` file must be between 500 and 5,000,000 characters.
 
-If it's too small: Review my documentation and add the full Markdown content of any missing pages, with each page separated by a `###` heading matching the page title.
+If the file is **too small**:
+- Review for missing pages or sections.
+- Add the full Markdown content of each missing page, separating each section with a `###` heading that matches the page title.
+- Ensure the file begins with a single H1 and meets the minimum heading and length requirements for discoverability.
+- If the file is still too small, suggest a plan to add more relevant, user-focused content.
 
-If it's too large: Identify the least essential content—verbose changelogs, auto-generated reference pages, or near-duplicate sections—and suggest what to remove or summarize to bring the file under 5,000,000 characters.
+If the file is **too large**:
+- Audit the content for lengthy changelogs, machine-generated reference pages, or redundant text.
+- Identify and recommend which sections to summarize or remove entirely, prioritizing core docs over verbose or duplicative material.
+- Streamline the file so it contains the most valuable information for AI, targeting a total size under 5,000,000 characters.
 
-Output a revised `llms-full.txt` within the valid range.
+When finished, output a revised `llms-full.txt` file within the valid range, preserving clarity and navigation for LLMs and agent applications.
 </Prompt>
 
 ### llms-full.txt valid structure
@@ -160,12 +214,13 @@ The file must start with an H1 heading and contain at least 2 headings total.
 **How to improve:** Mintlify-generated files always meet this requirement. For custom files, ensure each major documentation section starts with a heading.
 
 <Prompt description="Add heading structure to your `llms-full.txt` file." actions={["copy", "cursor"]}>
-My `llms-full.txt` file is missing the required heading structure—it must start with an H1 and contain at least 2 headings. Restructure it so that:
-- The first line is an H1 with the site name: `# Site Name`
-- Each major documentation section starts with a `##` heading
-- Individual pages within each section use `###` headings
+You have my `llms-full.txt` (paste or file). The readiness check requires: **first line is an H1** and **at least two Markdown headings total** (`#`, `##`, or `###`).
+
+Add the minimum heading structure without changing wording of body copy:
+- Line 1: `# <site or product name>` (derive from existing title or brand; no extra text on that line)
+- Introduce `##` for each major group (e.g. “Guides”, “API reference”) and `###` for each page or subsection, only where it improves navigation
 
-Preserve all existing content. Only add structure through headings. Output the complete restructured file.
+Do not strip sentences to hit heading count—only insert headings and blank lines as needed. Output the full file, then confirm heading count and that the first line is `# …`.
 </Prompt>
 
 ### llms-full.txt links resolve
@@ -177,12 +232,15 @@ At least 90% of same-origin links in the file must return HTTP 200.
 **How to improve:** Fix broken links in your documentation source.
 
 <Prompt description="Find and fix broken links in your `llms-full.txt` file." actions={["copy", "cursor"]}>
-My `llms-full.txt` file contains links that don't resolve. Review the links in the file and for each broken one:
-1. If the page moved, update the link to the new URL
-2. If the page was removed, delete the link and its surrounding content from the corpus
-3. If the URL format is wrong (missing `.md`, incorrect path prefix), fix it
+You have my `llms-full.txt` (paste or path). Same-origin links should resolve with HTTP 200 (readiness check: ≥90% success).
+
+For each same-origin link (ignore `mailto:`, `tel:`, and pure fragment-only URLs unless I ask otherwise):
+1. Note current URL and whether it returns 200 (infer from repo or state assumptions if you cannot fetch)
+2. If moved: replace with the canonical new URL
+3. If the path is wrong: fix prefixes, trailing slashes, or add `.md` where my host serves Markdown
+4. If the page is gone: prefer linking to a replacement doc or a short “removed—see …” line; only delete surrounding prose if the section has no value without that page
 
-Output the corrected `llms-full.txt` with all broken links resolved or removed.
+Deliver: corrected full file (or staged edits if too large), plus a table of changed URLs and what you did per row.
 </Prompt>
 
 ## skill.md
@@ -196,7 +254,19 @@ Mintlify automatically generates a `skill.md` file for every documentation site.
 **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.
 
 <Prompt description="Write a skill.md for your product" actions={["copy", "cursor"]}>
-Write a skill.md file for my product following the agentskills.io specification. Start with YAML frontmatter containing name, description, license, and compatibility fields. Then document: Capabilities (high-level things agents can accomplish), Skills (specific actions with required inputs and constraints), and Workflows (step-by-step procedures for common tasks). Focus on what agents can do programmatically, not just what product features exist. Keep descriptions precise and action-oriented.
+Draft a `skill.md` for my product that follows the [Agent Skills](https://agentskills.io) conventions and is suitable for discovery via `/.well-known/agent-skills/index.json` or `/skill.md`.
+
+Use YAML frontmatter at the top with at least: `name`, `description`, `license`, and `compatibility` (add other standard fields if useful).
+
+Body structure:
+1. **Overview** — One short paragraph: what the product is and who the agent user is
+2. **Capabilities** — Bullet list of outcomes agents can drive end-to-end (not marketing features)
+3. **Skills** — For each skill: purpose, required inputs, outputs, guardrails (auth, PII, rate limits), and failure modes
+4. **Workflows** — Numbered procedures for 2–4 common tasks, with decision points and when to escalate to a human
+
+Tone: imperative, testable statements. Avoid vague adjectives. If you lack product facts, insert `TODO` with the specific fact needed instead of guessing.
+
+Output the full `skill.md` in one fenced markdown block.
 </Prompt>
 
 ## Markdown content negotiation
@@ -210,7 +280,15 @@ Mintlify handles this automatically for all hosted documentation sites.
 **How to improve:** If you use a [reverse proxy](/deploy/reverse-proxy), ensure it forwards `Accept` headers to your Mintlify subdomain rather than stripping or overriding them.
 
 <Prompt description="Add Markdown content negotiation to your server" actions={["copy", "cursor"]}>
-I need my documentation server to support HTTP content negotiation for Markdown. When a client sends Accept: text/markdown or Accept: text/x-markdown, the server should respond with the Markdown source of the page and set Content-Type: text/markdown. Show me how to configure this for [your server framework or platform].
+I need HTTP content negotiation so that requests to my documentation root (and ideally each doc path) with `Accept: text/markdown, text/html;q=0.9` receive **Markdown**, not HTML: response body must be raw Markdown and `Content-Type` must be `text/markdown` or `text/x-markdown`.
+
+Constraints:
+- Default browser requests without that Accept header should still get normal HTML
+- Do not strip or rewrite the Accept header at a reverse proxy—forward it to the origin
+
+My stack: **&lt;name framework, host, and proxy, e.g. Next.js on Vercel behind Cloudflare&gt;**
+
+Give: (1) minimal example request/response headers, (2) exact config or middleware code for my stack, (3) a quick way to verify with `curl -H 'Accept: text/markdown' …`.
 </Prompt>
 
 ## Plaintext content negotiation
@@ -224,7 +302,11 @@ Mintlify handles this automatically for all hosted documentation sites.
 **How to improve:** Same as Markdown content negotiation—ensure your reverse proxy forwards `Accept` headers to Mintlify.
 
 <Prompt description="Add plain text content negotiation to your documentation server." actions={["copy", "cursor"]}>
-My documentation server needs to return plain text when a client sends `Accept: text/plain`. Configure it so that requests with `Accept: text/plain` return `Content-Type: text/plain` with a non-HTML body. Preserve normal HTML responses for browser requests. Show me the configuration for [your server platform or framework].
+Configure my docs origin so a request with `Accept: text/plain, text/html;q=0.9` gets a **non-HTML** `text/*` body (typically plain text derived from the same page content browsers see as HTML). Browsers sending default Accept headers must still receive HTML.
+
+My stack: **&lt;framework, host, reverse proxy if any&gt;**
+
+Provide: routing or middleware changes, how plain text differs from Markdown negotiation if both are supported, and a `curl` one-liner to confirm `Content-Type` and that the body is not HTML.
 </Prompt>
 
 ## MCP server
@@ -238,12 +320,16 @@ Mintlify hosts an MCP server for every documentation site. See [MCP server](/ai/
 **How to improve:** If you use a reverse proxy, configure it to forward `/mcp` to your Mintlify subdomain.
 
 <Prompt description="Expose an MCP server at `/mcp` on your documentation site." actions={["copy", "cursor"]}>
-I need to expose an MCP (Model Context Protocol) server at `/mcp` so AI agents can discover and call tools on my documentation site. My site is hosted on [your platform].
+I need a working MCP (Model Context Protocol) endpoint at `https://&lt;my-docs-domain&gt;/mcp` so agents can run `initialize` and discover tools.
+
+Requirements to satisfy:
+1. **JSON-RPC POST** to `/mcp`: `initialize` returns a result whose `serverInfo.name` is a non-empty string (this is what readiness checks look for)
+2. **`tools/list`** returns **at least one** tool with `name`, `description`, and `inputSchema` (JSON Schema object)
+3. If I use a reverse proxy or API gateway, show the exact path forwarding and any body-size or WebSocket settings MCP needs
 
-Show me how to:
-1. Set up an endpoint at `/mcp` that responds to JSON-RPC `initialize` requests with a valid `serverInfo` object containing a `name` field
-2. Handle the `tools/list` JSON-RPC method to return at least one tool definition
-3. Forward `/mcp` through my reverse proxy if one is in use
+My hosting: **&lt;platform, e.g. self-hosted Node, Cloudflare Workers, AWS ALB&gt;**
+
+Deliver: architecture sketch, minimal handler pseudocode or real code for my stack, and example `curl` bodies for `initialize` and `tools/list` I can paste to test.
 </Prompt>
 
 ### Tool count
@@ -255,13 +341,19 @@ After confirming the server is discoverable, the check calls `tools/list` and ve
 **How to improve:** See [MCP resources](/ai/model-context-protocol#mcp-resources) to understand which tools Mintlify exposes and how to configure them.
 
 <Prompt description="Add tools to your MCP server so agents have an actionable integration surface." actions={["copy", "cursor"]}>
-My MCP server at `/mcp` is reachable but returns no tools from `tools/list`. Add at least one tool so agents can take meaningful actions. For a documentation site, useful tools include:
+My MCP server at `/mcp` responds to `initialize` but `tools/list` is empty or returns zero tools. Fix it so **at least one** tool appears with valid `name`, `description`, and `inputSchema`.
+
+Prioritize doc-site tools that map to real behavior in my codebase:
+- **`search_docs`** — `query` string; returns ranked snippets + page URLs
+- **`get_page`** — `slug` or `url`; returns Markdown (or structured sections)
+- **`list_sections`** — no args or optional `locale`; returns nav tree
 
-- `search_docs`: Search documentation by query and return matching page excerpts
-- `get_page`: Fetch a specific page by URL or slug and return its Markdown content
-- `list_sections`: Return the top-level navigation structure
+Implementation asks:
+1. Register tools in one place so both `tools/list` and `tools/call` stay in sync
+2. Use JSON Schema for parameters (`type`, `properties`, `required` as appropriate)
+3. Add one happy-path test or manual `curl` showing `tools/list` non-empty
 
-Implement and register at least one of these so `tools/list` returns a valid tool definition with `name`, `description`, and `inputSchema`.
+Assume my repo layout: **&lt;monorepo path to MCP server if known&gt;**. If unknown, outline generic steps and file names to search.
 </Prompt>
 
 ## OpenAPI spec
@@ -273,7 +365,16 @@ The check looks for a valid spec at standard paths: `/openapi.json`, `/openapi.y
 **How to improve:** Host your OpenAPI spec at one of the standard paths listed above. If you already have a spec, verify it is publicly accessible without authentication.
 
 <Prompt description="Serve your OpenAPI spec at a standard path" actions={["copy", "cursor"]}>
-I want to make my OpenAPI spec discoverable to AI agents at /openapi.json or /openapi.yaml. Show me how to configure my server to serve the spec file at that path with the correct Content-Type header (application/json for JSON, application/x-yaml for YAML). The spec should be publicly accessible without authentication.
+Expose my OpenAPI document on the **public docs or API host** at one of the standard paths readiness checks probe: `/openapi.json`, `/openapi.yaml`, `/swagger.json`, `/swagger.yaml`, or `/api/` variants of those.
+
+Requirements:
+- Valid JSON or YAML with an `openapi` or `swagger` version field (must parse cleanly)
+- Correct `Content-Type` (`application/json` or `application/x-yaml` / `application/yaml` as appropriate)
+- No auth wall for GET (same behavior agents will see)
+
+My API is built with: **&lt;framework and where the spec is generated, e.g. FastAPI auto-schema, or a hand-maintained file at …&gt;**
+
+Give: exact static or dynamic route to add, cache headers if relevant, and a single `curl` command that prints the first lines and validates HTTP 200.
 </Prompt>
 
 ## robots.txt
@@ -285,7 +386,14 @@ The check fetches `/robots.txt` and verifies that none of the known AI agent use
 **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.
 
 <Prompt description="Update robots.txt to allow AI agents" actions={["copy", "cursor"]}>
-Review my robots.txt and update it to allow the major AI agent crawlers: GPTBot, ClaudeBot, Claude-User, Google-Extended, PerplexityBot, Copilot, and OAI-SearchBot. Preserve any existing rules for non-AI bots. If I currently have a wildcard User-agent: * rule with Disallow: /, show me how to add explicit Allow rules for AI agents above it.
+You have my current `robots.txt` (paste below). Update it so **no major AI agent user-agent** is blocked with `Disallow: /` or `Disallow: /*` (readiness checks flag patterns that blanket-block crawlers such as Claude, ChatGPT, Gemini, Copilot, Perplexity, and similar).
+
+Rules:
+- Prefer **path-specific** `Disallow` for sensitive areas instead of sitewide blocks for AI bots
+- Keep or improve rules for abusive scrapers if present—do not weaken protections unrelated to documentation
+- If `User-agent: *` is overly broad, add explicit `Allow` lines for doc paths for AI bots **or** narrow the wildcard rule; explain precedence so I do not accidentally keep a sitewide deny
+
+Output: full revised `robots.txt`, then a short “what changed” note listing each AI-related user-agent and its effective access to `/` and `/docs` (or my doc path prefix).
 </Prompt>
 
 ## Sitemap
@@ -299,7 +407,16 @@ Mintlify automatically generates and hosts a `sitemap.xml` for all documentation
 **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.
 
 <Prompt description="Generate a sitemap.xml for your docs site" actions={["copy", "cursor"]}>
-Generate a sitemap.xml for my documentation site. Include all public documentation pages with canonical URLs. Use the standard sitemap XML format with urlset, url, loc, and optionally lastmod and changefreq elements. The file should be served at /sitemap.xml with Content-Type: application/xml.
+Build a `sitemap.xml` for my documentation site that a readiness check can fetch at `/sitemap.xml` and recognize as XML (`Content-Type` `application/xml` or equivalent, or body starting with `<?xml`, `<urlset`, or `<sitemapindex`).
+
+Include:
+- Every **public** doc URL I care about crawlers indexing (canonical `https://` URLs, no auth-gated pages)
+- Optional `lastmod` if you can infer from git or file dates; otherwise omit rather than guess wildly
+- `changefreq` / `priority` only if my stack already uses them—do not invent policy I did not ask for
+
+Inputs I can provide: **&lt;base URL, list of routes, or “crawl this repo path”&gt;**
+
+Deliver: the XML file content plus where to place it in my build output so it is served at `/sitemap.xml`.
 </Prompt>
 
 ## Structured data
@@ -313,7 +430,17 @@ Mintlify embeds JSON-LD structured data automatically in all page responses.
 **How to improve:** Mintlify handles this automatically. If you host docs outside Mintlify, add JSON-LD markup to your page templates.
 
 <Prompt description="Add JSON-LD structured data to your documentation" actions={["copy", "cursor"]}>
-Add JSON-LD structured data to my documentation site. Include a WebSite schema on the homepage and a TechArticle or Article schema on individual documentation pages. Add BreadcrumbList markup for page hierarchy and Organization markup for the company. Show me where to place the `<script type="application/ld+json">` tag in my HTML template and what properties to include for a technical documentation site.
+Add JSON-LD to my documentation templates so pages include parseable `<script type="application/ld+json">` blocks (readiness checks scan the homepage HTML for valid JSON-LD).
+
+For each page type, propose minimal valid graphs:
+- **Home / docs root:** `WebSite` (name, url, optional `potentialAction` search)
+- **Article-style doc pages:** `TechArticle` or `Article` (headline, datePublished if available, author/org)
+- **All inner pages:** `BreadcrumbList` matching the sidebar hierarchy
+- **Organization** once (homepage or layout): name, url, logo if I have a stable URL
+
+My stack: **&lt;framework and templating, e.g. Docusaurus, Next.js App Router, Mintlify custom head&gt;**
+
+Show: exact template injection points, one example JSON-LD blob per page type filled with placeholders, and how to avoid duplicate `@id` collisions across routes.
 </Prompt>
 
 ## Response latency
@@ -325,5 +452,15 @@ The check times a direct request to your documentation root and passes if the fi
 **How to improve:** For Mintlify-hosted sites, response time is handled by Mintlify's infrastructure and should pass for most deployments. 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.
 
 <Prompt description="Diagnose slow documentation response time" actions={["copy", "cursor"]}>
-My documentation site is responding slowly (over 2 seconds to first byte). Help me identify the cause. Analyze: server-side rendering time, missing CDN or cache headers, unoptimized assets, third-party scripts blocking page load, and uncached database queries. Suggest specific changes to bring time-to-first-byte under 2 seconds. My site is hosted on [your hosting platform].
+My documentation **homepage/root** sometimes exceeds **2,000 ms time to first byte (TTFB)**—that fails our agent-readiness latency check (first byte must arrive within 2s).
+
+Help me triage in order:
+1. **Measure** — How to isolate TTFB vs total load (e.g. `curl -w '%{time_starttransfer}\n' -o /dev/null -s`, browser DevTools)
+2. **Edge vs origin** — CDN cache hit ratio, whether HTML is dynamically rendered per request, cold starts
+3. **Origin work** — SSR cost, data fetching on the critical path, region distance
+4. **Proxy misconfig** — buffering, auth subrequests, slow upstream health checks
+
+My setup: **&lt;hosting, CDN, proxy, framework&gt;**
+
+Return: top 3 likely causes for *my* stack, concrete settings or code changes to try first, and success criteria (which metric should drop below what threshold).
 </Prompt>

From a5cf2e30c357c44f6e64fdc645a0036c20438ee0 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 20 Apr 2026 16:44:38 -0700
Subject: [PATCH 08/15] =?UTF-8?q?=F0=9F=92=85?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ai/agent-readiness-checks.mdx | 44 ++++++++++++++++++-----------------
 1 file changed, 23 insertions(+), 21 deletions(-)

diff --git a/ai/agent-readiness-checks.mdx b/ai/agent-readiness-checks.mdx
index 783a6657e..80709c44d 100644
--- a/ai/agent-readiness-checks.mdx
+++ b/ai/agent-readiness-checks.mdx
@@ -207,45 +207,47 @@ When finished, output a revised `llms-full.txt` file within the valid range, pre
 
 ### llms-full.txt valid structure
 
-The file must start with an H1 heading and contain at least 2 headings total.
+The `llms-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.
 
-<Prompt description="Add heading structure to your `llms-full.txt` file." actions={["copy", "cursor"]}>
-You have my `llms-full.txt` (paste or file). The readiness check requires: **first line is an H1** and **at least two Markdown headings total** (`#`, `##`, or `###`).
-
-Add the minimum heading structure without changing wording of body copy:
-- Line 1: `# <site or product name>` (derive from existing title or brand; no extra text on that line)
-- Introduce `##` for each major group (e.g. “Guides”, “API reference”) and `###` for each page or subsection, only where it improves navigation
-
-Do not strip sentences to hit heading count—only insert headings and blank lines as needed. Output the full file, then confirm heading count and that the first line is `# …`.
+<Prompt description="Insert required heading structure into your `llms-full.txt` file." actions={["copy", "cursor"]}>
+Ensure the `llms-full.txt` file begins with an H1 heading (e.g., `# <site or product name>` on the very first line) and contains at least one additional heading. 
+
+Instructions:
+- Without altering any body content, insert headings where needed to meet these requirements.
+  - First line: Add a single H1 for the site or product name—do not add explanatory text on that line.
+  - Add `##` for each major section (such as "Guides", "API reference").
+  - Use `###` for pages or logical subsections where appropriate to improve navigation.
+- Do not modify or remove content just to increase heading count.
+- When finished, provide the updated file and verify that:
+  - The file starts with `# <site or product name>` as the first line.
+  - There are at least two Markdown headings in total.
 </Prompt>
 
 ### llms-full.txt links resolve
 
-At least 90% of same-origin links in the file must return HTTP 200.
+At least 90% of same-origin links in the `llms-full.txt` file must properly resolve and return an `HTTP 200` status code.
 
-**Why this check matters:** Same reasoning as the `llms.txt` links resolve check—broken references make content unreachable to agents following them.
+**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.
+**How to improve:** Fix broken links in your documentation source then update your `llms-full.txt` file.
 
 <Prompt description="Find and fix broken links in your `llms-full.txt` file." actions={["copy", "cursor"]}>
-You have my `llms-full.txt` (paste or path). Same-origin links should resolve with HTTP 200 (readiness check: ≥90% success).
-
-For each same-origin link (ignore `mailto:`, `tel:`, and pure fragment-only URLs unless I ask otherwise):
-1. Note current URL and whether it returns 200 (infer from repo or state assumptions if you cannot fetch)
-2. If moved: replace with the canonical new URL
-3. If the path is wrong: fix prefixes, trailing slashes, or add `.md` where my host serves Markdown
-4. If the page is gone: prefer linking to a replacement doc or a short “removed—see …” line; only delete surrounding prose if the section has no value without that page
+Audit all same-origin links in my `llms-full.txt` file. For each link that does not resolve to an `HTTP 200` status code:
+1. Determine the correct URL for the linked page.
+2. Update the link in the `llms-full.txt` file to point to the correct URL.
+3. Verify the link resolves correctly.
+4. After updating each broken link in your `llms-full.txt`, ensure you apply the exact same correction in the original source documentation file where that content is authored.
 
-Deliver: corrected full file (or staged edits if too large), plus a table of changed URLs and what you did per row.
+After fixing all broken links, provide the updated `llms-full.txt` file.
 </Prompt>
 
 ## skill.md
 
-The 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.
+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 automatically generates a `skill.md` file for every documentation site. See [skill.md](/ai/skillmd) for setup details and customization options.
 

From e9eb5e03c61b501520a5291c36b5f0b15155c365 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 20 Apr 2026 16:59:17 -0700
Subject: [PATCH 09/15] Update agent-readiness-checks.mdx

---
 ai/agent-readiness-checks.mdx | 69 ++++++++++++++++++-----------------
 1 file changed, 36 insertions(+), 33 deletions(-)

diff --git a/ai/agent-readiness-checks.mdx b/ai/agent-readiness-checks.mdx
index 80709c44d..7cf5e61e1 100644
--- a/ai/agent-readiness-checks.mdx
+++ b/ai/agent-readiness-checks.mdx
@@ -249,13 +249,13 @@ After fixing all broken links, provide the updated `llms-full.txt` file.
 
 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 automatically generates a `skill.md` file for every documentation site. See [skill.md](/ai/skillmd) for setup details and customization options.
+Mintlify generates a `skill.md` file for every documentation site. See [skill.md](/ai/skillmd) for customization options.
 
-**Why this check matters:** While `llms.txt` tells agents where your content is, `skill.md` tells agents what your product does and how to use it. This gives AI assistants the operating context they need to take meaningful actions on behalf of users—not just find information.
+**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.
 
-<Prompt description="Write a skill.md for your product" actions={["copy", "cursor"]}>
+<Prompt description="Write a `skill.md` for your product." actions={["copy", "cursor"]}>
 Draft a `skill.md` for my product that follows the [Agent Skills](https://agentskills.io) conventions and is suitable for discovery via `/.well-known/agent-skills/index.json` or `/skill.md`.
 
 Use YAML frontmatter at the top with at least: `name`, `description`, `license`, and `compatibility` (add other standard fields if useful).
@@ -264,56 +264,59 @@ Body structure:
 1. **Overview** — One short paragraph: what the product is and who the agent user is
 2. **Capabilities** — Bullet list of outcomes agents can drive end-to-end (not marketing features)
 3. **Skills** — For each skill: purpose, required inputs, outputs, guardrails (auth, PII, rate limits), and failure modes
-4. **Workflows** — Numbered procedures for 2–4 common tasks, with decision points and when to escalate to a human
+4. **Workflows** — Numbered procedures for 2-4 common tasks, with decision points and when to escalate to a human
 
 Tone: imperative, testable statements. Avoid vague adjectives. If you lack product facts, insert `TODO` with the specific fact needed instead of guessing.
 
-Output the full `skill.md` in one fenced markdown block.
+Output the full `skill.md` in one fenced markdown block. Call out any TODOs that must be resolved before the skill can be used.
 </Prompt>
 
 ## Markdown content negotiation
 
-The check sends a request to your documentation root with `Accept: 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.
+This check sends a request to your documentation root with `Accept: 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 clean, structured content without HTML overhead. This reduces token usage and removes noise from navigation elements, scripts, and markup.
+**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](/deploy/reverse-proxy), ensure it forwards `Accept` headers to your Mintlify subdomain rather than stripping or overriding them.
 
-<Prompt description="Add Markdown content negotiation to your server" actions={["copy", "cursor"]}>
-I need HTTP content negotiation so that requests to my documentation root (and ideally each doc path) with `Accept: text/markdown, text/html;q=0.9` receive **Markdown**, not HTML: response body must be raw Markdown and `Content-Type` must be `text/markdown` or `text/x-markdown`.
+<Prompt description="Implement Markdown content negotiation for your documentation server." actions={["copy", "cursor"]}>
+Configure the documentation server so that when a client sends a request with the `Accept: text/markdown, text/html;q=0.9` header to the root (and preferably any documentation path), it returns the raw Markdown source, not HTML. The HTTP response should have a `Content-Type` of either `text/markdown` or `text/x-markdown`. All other requests—such as those from browsers without this Accept header—must continue to return HTML as usual.
 
-Constraints:
-- Default browser requests without that Accept header should still get normal HTML
-- Do not strip or rewrite the Accept header at a reverse proxy—forward it to the origin
+Requirements:
+- Do not remove, transform, or ignore the `Accept` header at any reverse proxy—forward it to your origin server unchanged.
+- Only serve Markdown responses to requests explicitly asking for them via `Accept`.
+
+The response should include:
+1. Minimal example of request and response headers for both HTML and Markdown negotiations.
+2. The exact middleware or server configuration needed.
+3. A short `curl` command to test that Markdown negotiation works (ensure it checks both the `Content-Type` and body output, demonstrating Markdown is served).
 
-My stack: **&lt;name framework, host, and proxy, e.g. Next.js on Vercel behind Cloudflare&gt;**
+Optional: If content negotiation for individual documentation pages as well as the root is supported, describe any additional setup needed.
 
-Give: (1) minimal example request/response headers, (2) exact config or middleware code for my stack, (3) a quick way to verify with `curl -H 'Accept: text/markdown' …`.
+Be concise. Focus only on the changes or code/configuration necessary for robust Markdown negotiation.
 </Prompt>
 
 ## Plaintext content negotiation
 
-The check sends a request to your documentation root with `Accept: text/plain, text/html;q=0.9` and verifies that the response returns a non-HTML `text/*` content type.
+This check sends a request to your documentation root with `Accept: 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 and tools cannot handle Markdown and fall back to plain text. Supporting this keeps your content accessible to simpler clients.
+**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:** Same as Markdown content negotiation—ensure your reverse proxy forwards `Accept` headers to Mintlify.
+**How to improve:** If you use a reverse proxy, ensure it forwards `Accept` headers to your Mintlify subdomain.
 
 <Prompt description="Add plain text content negotiation to your documentation server." actions={["copy", "cursor"]}>
-Configure my docs origin so a request with `Accept: text/plain, text/html;q=0.9` gets a **non-HTML** `text/*` body (typically plain text derived from the same page content browsers see as HTML). Browsers sending default Accept headers must still receive HTML.
-
-My stack: **&lt;framework, host, reverse proxy if any&gt;**
+Configure the documentation server so a request with `Accept: text/plain, text/html;q=0.9` gets a **non-HTML** `text/*` body. Browsers sending default Accept headers must still receive HTML.
 
-Provide: routing or middleware changes, how plain text differs from Markdown negotiation if both are supported, and a `curl` one-liner to confirm `Content-Type` and that the body is not HTML.
+Provide: routing or middleware changes, how plain text differs from Markdown negotiation if both are supported, and a `curl` command to confirm `Content-Type` and that the body is not HTML.
 </Prompt>
 
 ## MCP server
 
-The check sends a JSON-RPC `initialize` request to `{yourDomain}/mcp` using the MCP protocol. It passes if the response includes a valid `serverInfo.name`.
+This check sends a JSON-RPC `initialize` request to `/mcp` on your domain. It passes if the response includes a valid `serverInfo.name`.
 
 Mintlify hosts an MCP server for every documentation site. See [MCP server](/ai/model-context-protocol) for details and configuration.
 
@@ -336,7 +339,7 @@ Deliver: architecture sketch, minimal handler pseudocode or real code for my sta
 
 ### Tool count
 
-After confirming the server is discoverable, the check calls `tools/list` and verifies at least one tool is returned.
+The check calls `tools/list` and verifies at least one tool is returned.
 
 **Why this check matters:** An MCP server with no tools offers no actionable integration surface for agents.
 
@@ -360,13 +363,13 @@ Assume my repo layout: **&lt;monorepo path to MCP server if known&gt;**. If unkn
 
 ## OpenAPI spec
 
-The check looks for a valid spec at standard paths: `/openapi.json`, `/openapi.yaml`, `/swagger.json`, `/swagger.yaml`, and `/api/` variants of each. The spec must parse as valid JSON or YAML with an `openapi` or `swagger` version field.
+This check looks for a valid spec at standard paths: `/openapi.json`, `/openapi.yaml`, `/swagger.json`, `/swagger.yaml`, and `/api/` variants of each. The spec must parse as valid JSON or YAML with an `openapi` or `swagger` version field.
 
 **Why this check matters:** A discoverable OpenAPI spec lets agents auto-discover your API surface, parameters, and schemas without scraping documentation HTML. This is the most direct path for agents to call your API accurately.
 
 **How to improve:** Host your OpenAPI spec at one of the standard paths listed above. If you already have a spec, verify it is publicly accessible without authentication.
 
-<Prompt description="Serve your OpenAPI spec at a standard path" actions={["copy", "cursor"]}>
+<Prompt description="Serve your OpenAPI spec at a standard path." actions={["copy", "cursor"]}>
 Expose my OpenAPI document on the **public docs or API host** at one of the standard paths readiness checks probe: `/openapi.json`, `/openapi.yaml`, `/swagger.json`, `/swagger.yaml`, or `/api/` variants of those.
 
 Requirements:
@@ -381,13 +384,13 @@ Give: exact static or dynamic route to add, cache headers if relevant, and a sin
 
 ## robots.txt
 
-The 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.
+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.
 
-<Prompt description="Update robots.txt to allow AI agents" actions={["copy", "cursor"]}>
+<Prompt description="Update `robots.txt` to allow AI agents." actions={["copy", "cursor"]}>
 You have my current `robots.txt` (paste below). Update it so **no major AI agent user-agent** is blocked with `Disallow: /` or `Disallow: /*` (readiness checks flag patterns that blanket-block crawlers such as Claude, ChatGPT, Gemini, Copilot, Perplexity, and similar).
 
 Rules:
@@ -400,7 +403,7 @@ Output: full revised `robots.txt`, then a short “what changed” note listing
 
 ## Sitemap
 
-The check fetches `/sitemap.xml` and verifies it returns a valid XML content type or starts with valid XML (`<?xml`, `<urlset`, or `<sitemapindex`).
+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.
 
@@ -408,7 +411,7 @@ Mintlify automatically generates and hosts a `sitemap.xml` for all documentation
 
 **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.
 
-<Prompt description="Generate a sitemap.xml for your docs site" actions={["copy", "cursor"]}>
+<Prompt description="Generate a `sitemap.xml` for your documentation site." actions={["copy", "cursor"]}>
 Build a `sitemap.xml` for my documentation site that a readiness check can fetch at `/sitemap.xml` and recognize as XML (`Content-Type` `application/xml` or equivalent, or body starting with `<?xml`, `<urlset`, or `<sitemapindex`).
 
 Include:
@@ -423,7 +426,7 @@ Deliver: the XML file content plus where to place it in my build output so it is
 
 ## Structured data
 
-The check fetches your documentation homepage as HTML and looks for `<script type="application/ld+json">` tags containing parseable JSON-LD.
+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.
 
@@ -431,7 +434,7 @@ Mintlify embeds JSON-LD structured data automatically in all page responses.
 
 **How to improve:** Mintlify handles this automatically. If you host docs outside Mintlify, add JSON-LD markup to your page templates.
 
-<Prompt description="Add JSON-LD structured data to your documentation" actions={["copy", "cursor"]}>
+<Prompt description="Add JSON-LD structured data to your documentation site." actions={["copy", "cursor"]}>
 Add JSON-LD to my documentation templates so pages include parseable `<script type="application/ld+json">` blocks (readiness checks scan the homepage HTML for valid JSON-LD).
 
 For each page type, propose minimal valid graphs:
@@ -447,13 +450,13 @@ Show: exact template injection points, one example JSON-LD blob per page type fi
 
 ## Response latency
 
-The check times a direct request to your documentation root and passes if the first byte arrives within 2,000 milliseconds. The check fails if the request times out.
+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 2-second threshold accounts for agent processing overhead on top of network time.
 
 **How to improve:** For Mintlify-hosted sites, response time is handled by Mintlify's infrastructure and should pass for most deployments. 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.
 
-<Prompt description="Diagnose slow documentation response time" actions={["copy", "cursor"]}>
+<Prompt description="Diagnose and fix slow documentation response time." actions={["copy", "cursor"]}>
 My documentation **homepage/root** sometimes exceeds **2,000 ms time to first byte (TTFB)**—that fails our agent-readiness latency check (first byte must arrive within 2s).
 
 Help me triage in order:

From 530e81884492719fc328fd430638a70737b50a31 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 20 Apr 2026 17:01:48 -0700
Subject: [PATCH 10/15] Update agent-readiness-checks.mdx

---
 ai/agent-readiness-checks.mdx | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/ai/agent-readiness-checks.mdx b/ai/agent-readiness-checks.mdx
index 7cf5e61e1..98eb71f89 100644
--- a/ai/agent-readiness-checks.mdx
+++ b/ai/agent-readiness-checks.mdx
@@ -316,32 +316,30 @@ Provide: routing or middleware changes, how plain text differs from Markdown neg
 
 ## MCP server
 
-This check sends a JSON-RPC `initialize` request to `/mcp` on your domain. It passes if the response includes a valid `serverInfo.name`.
+This check sends a JSON-RPC `initialize` 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](/ai/model-context-protocol) for details and configuration.
 
-**Why this check matters:** An MCP server gives agents a first-class integration path with structured tools and typed outputs, rather than forcing them to scrape HTML or infer behavior from documentation.
+**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.
 
 <Prompt description="Expose an MCP server at `/mcp` on your documentation site." actions={["copy", "cursor"]}>
-I need a working MCP (Model Context Protocol) endpoint at `https://&lt;my-docs-domain&gt;/mcp` so agents can run `initialize` and discover tools.
+I need a working MCP (Model Context Protocol) endpoint at `/mcp` subdomain of my documentation site so agents can run `initialize` and discover tools.
 
 Requirements to satisfy:
 1. **JSON-RPC POST** to `/mcp`: `initialize` returns a result whose `serverInfo.name` is a non-empty string (this is what readiness checks look for)
 2. **`tools/list`** returns **at least one** tool with `name`, `description`, and `inputSchema` (JSON Schema object)
 3. If I use a reverse proxy or API gateway, show the exact path forwarding and any body-size or WebSocket settings MCP needs
 
-My hosting: **&lt;platform, e.g. self-hosted Node, Cloudflare Workers, AWS ALB&gt;**
-
 Deliver: architecture sketch, minimal handler pseudocode or real code for my stack, and example `curl` bodies for `initialize` and `tools/list` I can paste to test.
 </Prompt>
 
 ### Tool count
 
-The check calls `tools/list` and verifies at least one tool is returned.
+This check calls `tools/list` and verifies at least one tool is returned.
 
-**Why this check matters:** An MCP server with no tools offers no actionable integration surface for agents.
+**Why this check matters:** An MCP server with no tools offers no integrations for agents.
 
 **How to improve:** See [MCP resources](/ai/model-context-protocol#mcp-resources) to understand which tools Mintlify exposes and how to configure them.
 

From aa1471439a3d8487e43df6b8cb301ff05203fdd0 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 20 Apr 2026 17:03:07 -0700
Subject: [PATCH 11/15] tool check

---
 ai/agent-readiness-checks.mdx | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/ai/agent-readiness-checks.mdx b/ai/agent-readiness-checks.mdx
index 98eb71f89..59d7f0530 100644
--- a/ai/agent-readiness-checks.mdx
+++ b/ai/agent-readiness-checks.mdx
@@ -341,7 +341,7 @@ This check calls `tools/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:** See [MCP resources](/ai/model-context-protocol#mcp-resources) to understand which tools Mintlify exposes and how to configure them.
+**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`.
 
 <Prompt description="Add tools to your MCP server so agents have an actionable integration surface." actions={["copy", "cursor"]}>
 My MCP server at `/mcp` responds to `initialize` but `tools/list` is empty or returns zero tools. Fix it so **at least one** tool appears with valid `name`, `description`, and `inputSchema`.
@@ -355,8 +355,6 @@ Implementation asks:
 1. Register tools in one place so both `tools/list` and `tools/call` stay in sync
 2. Use JSON Schema for parameters (`type`, `properties`, `required` as appropriate)
 3. Add one happy-path test or manual `curl` showing `tools/list` non-empty
-
-Assume my repo layout: **&lt;monorepo path to MCP server if known&gt;**. If unknown, outline generic steps and file names to search.
 </Prompt>
 
 ## OpenAPI spec

From efcb5dc174191678986ab0e9b97882b589619bfc Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 20 Apr 2026 17:05:45 -0700
Subject: [PATCH 12/15] openapi

---
 ai/agent-readiness-checks.mdx | 26 +++++++++++++++-----------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/ai/agent-readiness-checks.mdx b/ai/agent-readiness-checks.mdx
index 59d7f0530..ba6eb7e0d 100644
--- a/ai/agent-readiness-checks.mdx
+++ b/ai/agent-readiness-checks.mdx
@@ -357,25 +357,29 @@ Implementation asks:
 3. Add one happy-path test or manual `curl` showing `tools/list` non-empty
 </Prompt>
 
-## OpenAPI spec
+## OpenAPI specification
 
-This check looks for a valid spec at standard paths: `/openapi.json`, `/openapi.yaml`, `/swagger.json`, `/swagger.yaml`, and `/api/` variants of each. The spec must parse as valid JSON or YAML with an `openapi` or `swagger` version field.
+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 spec lets agents auto-discover your API surface, parameters, and schemas without scraping documentation HTML. This is the most direct path for agents to call your API accurately.
+**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 spec at one of the standard paths listed above. If you already have a spec, verify it is publicly accessible without authentication.
+**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.
 
-<Prompt description="Serve your OpenAPI spec at a standard path." actions={["copy", "cursor"]}>
-Expose my OpenAPI document on the **public docs or API host** at one of the standard paths readiness checks probe: `/openapi.json`, `/openapi.yaml`, `/swagger.json`, `/swagger.yaml`, or `/api/` variants of those.
+<Prompt description="Serve your OpenAPI specification at a standard path." actions={["copy", "cursor"]}>
+I want my OpenAPI specification publicly accessible at one of these standard paths so agents can discover it without scraping my docs: `/openapi.json`, `/openapi.yaml`, `/swagger.json`, `/swagger.yaml`, or `/api/` variants of each.
 
 Requirements:
-- Valid JSON or YAML with an `openapi` or `swagger` version field (must parse cleanly)
-- Correct `Content-Type` (`application/json` or `application/x-yaml` / `application/yaml` as appropriate)
-- No auth wall for GET (same behavior agents will see)
+- The spec must be valid JSON or YAML with an `openapi` or `swagger` version field at the top level
+- Correct `Content-Type`: `application/json` for JSON specs, `application/yaml` or `application/x-yaml` for YAML
+- No authentication required for GET requests—the spec must be publicly readable
 
-My API is built with: **&lt;framework and where the spec is generated, e.g. FastAPI auto-schema, or a hand-maintained file at …&gt;**
+My API framework: **&lt;e.g. FastAPI, Express, Rails, hand-maintained file&gt;**
+Where the spec currently lives: **&lt;e.g. auto-generated at runtime, static file at path/to/openapi.yaml&gt;**
 
-Give: exact static or dynamic route to add, cache headers if relevant, and a single `curl` command that prints the first lines and validates HTTP 200.
+Deliver:
+1. The exact route or server config to serve the spec at the correct path
+2. Whether to prefer JSON or YAML given my stack, and why
+3. A `curl` one-liner to confirm the spec is reachable and parses correctly: `curl -s https://yourdomain.com/openapi.json | head -5`
 </Prompt>
 
 ## robots.txt

From a665ef95bde2fb765cd1eb6e4b9bb64123a2565e Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Mon, 20 Apr 2026 17:10:37 -0700
Subject: [PATCH 13/15] update prompts

---
 ai/agent-readiness-checks.mdx | 70 +++++++++++++++++++----------------
 1 file changed, 38 insertions(+), 32 deletions(-)

diff --git a/ai/agent-readiness-checks.mdx b/ai/agent-readiness-checks.mdx
index ba6eb7e0d..e74d928c6 100644
--- a/ai/agent-readiness-checks.mdx
+++ b/ai/agent-readiness-checks.mdx
@@ -391,14 +391,16 @@ This check fetches `/robots.txt` and verifies that none of the known AI agent us
 **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.
 
 <Prompt description="Update `robots.txt` to allow AI agents." actions={["copy", "cursor"]}>
-You have my current `robots.txt` (paste below). Update it so **no major AI agent user-agent** is blocked with `Disallow: /` or `Disallow: /*` (readiness checks flag patterns that blanket-block crawlers such as Claude, ChatGPT, Gemini, Copilot, Perplexity, and similar).
+My `robots.txt` may be blocking AI crawlers. Update it so none of these user-agents are blocked with `Disallow: /` or `Disallow: /*`: `GPTBot`, `ClaudeBot`, `Claude-User`, `Google-Extended`, `PerplexityBot`, `Copilot`, `OAI-SearchBot`.
 
 Rules:
-- Prefer **path-specific** `Disallow` for sensitive areas instead of sitewide blocks for AI bots
-- Keep or improve rules for abusive scrapers if present—do not weaken protections unrelated to documentation
-- If `User-agent: *` is overly broad, add explicit `Allow` lines for doc paths for AI bots **or** narrow the wildcard rule; explain precedence so I do not accidentally keep a sitewide deny
+- Use path-specific `Disallow` for sensitive areas rather than sitewide blocks for AI crawlers
+- Preserve existing rules for non-AI bots—do not weaken unrelated protections
+- If `User-agent: *` has a broad `Disallow`, add explicit `Allow` lines for AI crawlers above it and explain precedence
 
-Output: full revised `robots.txt`, then a short “what changed” note listing each AI-related user-agent and its effective access to `/` and `/docs` (or my doc path prefix).
+Deliver:
+1. The complete revised `robots.txt`
+2. A summary of what changed for each AI-related user-agent and its effective access to my documentation path
 </Prompt>
 
 ## Sitemap
@@ -412,16 +414,17 @@ Mintlify automatically generates and hosts a `sitemap.xml` for all documentation
 **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.
 
 <Prompt description="Generate a `sitemap.xml` for your documentation site." actions={["copy", "cursor"]}>
-Build a `sitemap.xml` for my documentation site that a readiness check can fetch at `/sitemap.xml` and recognize as XML (`Content-Type` `application/xml` or equivalent, or body starting with `<?xml`, `<urlset`, or `<sitemapindex`).
+I need a `sitemap.xml` served at `/sitemap.xml` so agents and crawlers can discover all my documentation URLs without guessing at navigation.
 
 Include:
-- Every **public** doc URL I care about crawlers indexing (canonical `https://` URLs, no auth-gated pages)
-- Optional `lastmod` if you can infer from git or file dates; otherwise omit rather than guess wildly
-- `changefreq` / `priority` only if my stack already uses them—do not invent policy I did not ask for
-
-Inputs I can provide: **&lt;base URL, list of routes, or “crawl this repo path”&gt;**
+- Every public documentation URL in canonical `https://` form—no auth-gated pages
+- `lastmod` if you can derive it from git history or file dates; omit it rather than guess
+- `changefreq` and `priority` only if my framework already generates them
 
-Deliver: the XML file content plus where to place it in my build output so it is served at `/sitemap.xml`.
+Deliver:
+1. The complete `sitemap.xml` file content
+2. Where to place it so it is served at `/sitemap.xml` in my build output
+3. A `curl` one-liner to confirm it's reachable and recognized as XML: `curl -sI https://yourdomain.com/sitemap.xml | grep content-type`
 </Prompt>
 
 ## Structured data
@@ -430,42 +433,45 @@ This check fetches your documentation homepage as HTML and looks for `<script ty
 
 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.
+**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.
 
 <Prompt description="Add JSON-LD structured data to your documentation site." actions={["copy", "cursor"]}>
-Add JSON-LD to my documentation templates so pages include parseable `<script type="application/ld+json">` blocks (readiness checks scan the homepage HTML for valid JSON-LD).
-
-For each page type, propose minimal valid graphs:
-- **Home / docs root:** `WebSite` (name, url, optional `potentialAction` search)
-- **Article-style doc pages:** `TechArticle` or `Article` (headline, datePublished if available, author/org)
-- **All inner pages:** `BreadcrumbList` matching the sidebar hierarchy
-- **Organization** once (homepage or layout): name, url, logo if I have a stable URL
+I need parseable `<script type="application/ld+json">` blocks on my documentation pages so agents can read machine-readable context about my site structure and content.
 
-My stack: **&lt;framework and templating, e.g. Docusaurus, Next.js App Router, Mintlify custom head&gt;**
+For each page type, add a minimal valid JSON-LD graph:
+- **Homepage / docs root:** `WebSite` with `name`, `url`, and optional `potentialAction` for site search
+- **Doc pages:** `TechArticle` or `Article` with `headline`, `datePublished` if available, and `author` or `organization`
+- **All inner pages:** `BreadcrumbList` matching the page's position in the navigation hierarchy
+- **Once in the layout:** `Organization` with `name`, `url`, and `logo`
 
-Show: exact template injection points, one example JSON-LD blob per page type filled with placeholders, and how to avoid duplicate `@id` collisions across routes.
+Deliver:
+1. Exact template injection points for each page type in my stack
+2. One complete example JSON-LD blob per page type with realistic placeholders
+3. How to keep `@id` values unique across routes to avoid collisions
+4. How to verify: open DevTools → Elements → search for `application/ld+json`
 </Prompt>
 
 ## 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 2-second threshold accounts for agent processing overhead on top of network time.
+**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:** For Mintlify-hosted sites, response time is handled by Mintlify's infrastructure and should pass for most deployments. 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.
+**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.
 
 <Prompt description="Diagnose and fix slow documentation response time." actions={["copy", "cursor"]}>
-My documentation **homepage/root** sometimes exceeds **2,000 ms time to first byte (TTFB)**—that fails our agent-readiness latency check (first byte must arrive within 2s).
+My documentation homepage is exceeding 2,000 ms time to first byte (TTFB), which fails the agent-readiness latency check.
 
 Help me triage in order:
-1. **Measure** — How to isolate TTFB vs total load (e.g. `curl -w '%{time_starttransfer}\n' -o /dev/null -s`, browser DevTools)
-2. **Edge vs origin** — CDN cache hit ratio, whether HTML is dynamically rendered per request, cold starts
-3. **Origin work** — SSR cost, data fetching on the critical path, region distance
-4. **Proxy misconfig** — buffering, auth subrequests, slow upstream health checks
-
-My setup: **&lt;hosting, CDN, proxy, framework&gt;**
+1. **Measure** — Isolate TTFB from total load time: `curl -w '%{time_starttransfer}\n' -o /dev/null -s https://yourdomain.com` and browser DevTools Network tab
+2. **Edge vs origin** — CDN cache hit ratio, whether HTML is server-rendered per request, cold start behavior
+3. **Origin bottlenecks** — SSR render cost, blocking data fetches on the critical path, server region vs. user location
+4. **Proxy misconfiguration** — Response buffering, auth subrequests adding latency, slow upstream health checks
 
-Return: top 3 likely causes for *my* stack, concrete settings or code changes to try first, and success criteria (which metric should drop below what threshold).
+Deliver:
+1. The top 3 most likely causes for my specific stack
+2. Concrete configuration changes or code edits to try first
+3. How to verify the fix: TTFB should drop below 1,500 ms measured with the `curl` command above
 </Prompt>

From 8a023f770276d8f10ac9539ea04640cb20747607 Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 22 Apr 2026 13:54:28 -0700
Subject: [PATCH 14/15] add overview table

---
 ai/agent-readiness-checks.mdx | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/ai/agent-readiness-checks.mdx b/ai/agent-readiness-checks.mdx
index e74d928c6..acf3da08c 100644
--- a/ai/agent-readiness-checks.mdx
+++ b/ai/agent-readiness-checks.mdx
@@ -14,6 +14,20 @@ For example, if your site has no `llms.txt` file, none of the checks that evalua
 
 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 |
+
 <Tip>
   Every check includes a ready-to-use prompt for improving your documentation and passing the check and any dependent checks.
 

From 59cd45c021b6cdcce76cb90cdbb83283e78617ba Mon Sep 17 00:00:00 2001
From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
Date: Wed, 22 Apr 2026 13:57:36 -0700
Subject: [PATCH 15/15] fix URL

---
 ai/agent-readiness-checks.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ai/agent-readiness-checks.mdx b/ai/agent-readiness-checks.mdx
index acf3da08c..bfe68bbd7 100644
--- a/ai/agent-readiness-checks.mdx
+++ b/ai/agent-readiness-checks.mdx
@@ -4,7 +4,7 @@ description: "What each Agent Rank check tests, why it matters, and how to make
 keywords: ["agent rank", "agent friendly"]
 ---
 
-[Agent Rank](https://agentrank.mintlify.com) scores your documentation site on how accessible it is to AI agents. This page explains what each agent readiness check tests, why it matters, and how to make your documentation more agent friendly.
+[Agent Rank](https://agentrank.io) scores your documentation site on how accessible it is to AI agents. This page explains what each agent readiness check tests, why it matters, and how to make your documentation more agent friendly.
 
 ## How scoring works