What Is Markdown For Agents Checker

• When teams search for 'what is markdown for agents checker,' they often conflate two separate problems.
• Websites that support Markdown for Agents use four complementary mechanisms to serve content in Markdown format to AI agents.
• Markdown reduces token usage by up to 80-90% compared to HTML.
• Tools that validate whether a website serves Markdown to AI agents simulate bot requests and measure the response.
• mdcheck is a deterministic markdown validation tool designed for AI agents writing markdown.

When teams search for 'what is markdown for agents checker,' they often conflate two separate problems. The first is content delivery: does your website serve Markdown when AI crawlers request it with an Accept: text/markdown header? Tools like Testomato and Keep.md test this directly by simulating AI bot requests and checking whether your server responds with Markdown instead of HTML. The second is document validation:

• Checking frontmatter
• Section order
• List formatting
• Link resolution
• According to the GitHub markdown-checker repository

One problem is about serving content to external AI agents; the other is about validating content your own agents produce. Conflating them leads to choosing the wrong tool.

Websites that support Markdown for Agents use four complementary mechanisms to serve content in Markdown format to AI agents. According to AgentReady.md and Testomato, these mechanisms are content negotiation via the Accept:

• Text/markdown HTTP header

-.md URL variants

• HTML <link> tags with rel="alternate" type="text/markdown"
• HTTP Link headers

Content negotiation via the Accept: text/markdown header tells the server which format the client prefers; the server responds with Markdown instead of HTML. URL variants, serving the same page at both example.com/page and example.com/page.md, let agents request Markdown directly. HTML <link> tags with rel="alternate" type="text/markdown" point crawlers to Markdown versions of pages. HTTP Link headers in the response do the same thing programmatically. When an AI agent like GPTBot or ClaudeBot fetches a page, it can request Markdown, reducing the token cost of parsing the response. According to Testomato, the Vary: Accept response header ensures caches store Markdown and HTML separately, preventing one format from being served to the wrong client.

Markdown reduces token usage by up to 80-90% compared to HTML. According to Testomato and Wux Webtools, Markdown excludes scripts, stylesheets, and other HTML tags that HTML requires but AI agents don't need. An HTML page with navigation, analytics, and CSS inline might consume 2,000 tokens; the same content in clean Markdown uses 200 to 400 tokens.

This matters because AI agents operate under context-window constraints. Perplexity, Claude, and ChatGPT can only hold so much information in memory at once. Serving Markdown instead of HTML lets agents fetch more pages, retrieve longer documents, or allocate more context to reasoning, all without hitting token limits.

For websites trying to earn AI citations, this efficiency gain makes the difference between being crawled thoroughly and being skipped. Cloudflare's Markdown for Agents feature automatically converts HTML to Markdown at the edge when AI bots request it, and the x-markdown-tokens header lets agents estimate token cost before fetching the full response.

Tools that validate whether a website serves Markdown to AI agents simulate bot requests and measure the response. Testomato's free checker sends an Accept: text/markdown header to your domain and reports whether the server responds with Markdown, HTML, or an HTTP 406 Not Acceptable error. Keep.md and Wux Webtools offer similar testing. These tools check whether your Content Delivery Network, web server, or application correctly handles content negotiation. However, many servers return HTML with a 200 status code even when they cannot serve Markdown. According to Testomato, the HTTP 406 Not Acceptable status code is the correct response when a server cannot satisfy an Accept header, though it is rarely used in practice. Running these checkers reveals whether your site is actually optimized for AI crawlers or whether the Markdown for Agents infrastructure is missing. Specifically, they do not validate the quality or structure of the Markdown itself:

• They only confirm that Markdown is being served
• They test content negotiation and header handling
• They identify missing Markdown for Agents infrastructure
• They do not validate document structure or quality

These validators ensure external agents can fetch your content efficiently.

mdcheck is a deterministic markdown validation tool designed for AI agents writing markdown. According to the GitHub markdown-checker repository, mdcheck uses declarative YAML rules with CSS-like selectors to check document structure. Unlike content-delivery checkers, mdcheck validates the Markdown that agents produce, ensuring frontmatter exists, sections appear in the correct order, lists use consistent formatting, tables have the right number of columns, and links resolve. Specifically, mdcheck validates multiple structural elements:

• Frontmatter requirements and section ordering
• List formatting and table column definitions
• Link resolution and text constraints
• Machine-readable JSON output for CI gates

According to the GitHub markdown-checker repository, mdcheck outputs results in machine-readable JSON format, making it suitable as a CI gate for human reviewers and as a promptfoo assertion for evaluation suites that test agent output. A single binary with no scripting or plugin API means teams can integrate mdcheck into their development pipeline without adding complexity. This tool solves a different problem than content-delivery validators: it ensures that when your agents write Markdown, the output meets your specifications. The two tools address different workflows; one tests whether external agents can fetch your content efficiently; the other ensures internal agents produce valid, consistent output.

An AGENTS.md file is a markdown configuration file checked into Git that customizes how AI coding agents behave in a repository, according to AI Hero. It contains personal scope guidance (commit style, coding patterns, naming conventions) and project scope guidance (project description, package manager, architecture decisions, dependencies). Frontier LLMs can follow approximately 150-200 instructions with reasonable consistency; smaller and non-thinking models attend to fewer instructions, creating a hard token budget problem for large AGENTS.md files.

Check Run Agents are markdown files in a.macroscope/check-run-agents/ directory that define custom AI agents for GitHub pull requests, with optional YAML frontmatter controlling model selection, reasoning depth, investigation depth, and tool access.

Both are markdown-based configuration tools, but AGENTS.md is repository-wide guidance for any agent working in that codebase, while Check Run Agents are task-specific agents triggered by pull requests. Neither is a content-delivery mechanism or a validation tool, they are instructions for AI agents themselves.

Websites communicate content policies to AI agents using HTTP response headers. According to Wux Webtools, Content-Signal headers such as ai-train=yes or ai-train=no tell crawlers whether they are allowed to use the content for training.

The Vary: Accept header signals that response content differs depending on the client's Accept header, according to Testomato, ensuring caches store Markdown and HTML versions independently. The x-markdown-tokens header, supported by Cloudflare and documented in Keep.md and Testomato, provides an estimated token count when converting pages to Markdown at the edge, allowing AI agents to budget their context window before fetching the full response.

These headers are not validation tools; they are signals that control how AI agents treat your content. Setting headers correctly ensures that agents can discover Markdown versions, respect your training preferences, and make efficient decisions about what to fetch.

Choosing the right checker depends on your optimization goal. If your goal is to optimize your website for AI crawlers, use a content-delivery validator like Testomato or Keep.md to confirm that your server responds with Markdown when agents request it. If your goal is to ensure that AI agents writing code in your repository produce valid Markdown, use mdcheck as a CI gate. If you are configuring how agents should behave in your codebase, write an AGENTS.md file and keep it under the instruction budget (approximately 150-200 instructions for frontier models, according to AI Hero and Humanlayer):

• Content-delivery validators test Markdown serving to external agents
• mdcheck validates Markdown structure from internal agents
• AGENTS.md configures agent behavior in repositories

The mistake teams make is running a content-delivery checker expecting it to validate Markdown structure, or using mdcheck expecting it to test whether your website serves Markdown to external agents. Each tool solves one problem well. Combining them, validating both content delivery and document structure, gives you full visibility into whether your site is AI-agent-ready and whether your agent-generated output meets your standards.

The specific figures and claims on this page are grounded in the following sources, reviewed at the time of writing:

• GitHub - A/markdown-checker: Deterministic specs for markdown documents, declarative YAML rules, CSS-like selectors, machine-readable findi
• Markdown for Agents Checker: AI readiness for your website
• Free Markdown for Agents Checker
• A Complete Guide To AGENTS.md
• Markdown Negotiation Tester, AgentReady.md
• AI Markdown Checker - Test Cloudflare Markdown for Agents - Wux Webtools