# Agent Ready

## Overview

Agent Ready is a website scanner that checks agent readability compliance. It scores sites against three specifications:

1. **Vercel Agent Readability Spec** - 15 site-wide + 23 per-page checks (score 0-100)
2. **llmstxt.org spec** - 10 checks on the /llms.txt file (weighted score 0-100)
3. **Agent protocols** - 7 checks covering MCP server cards, A2A agent cards, agents.json, and agent-permissions.json

Feature-specific validator pages (free, no auth):

- [/llms-txt-checker](https://agent-ready.dev/llms-txt-checker)
- [/agents-md-validator](https://agent-ready.dev/agents-md-validator)
- [/mcp-card-validator](https://agent-ready.dev/mcp-card-validator)
- [/agent-card-validator](https://agent-ready.dev/agent-card-validator)
- [/agents-json-validator](https://agent-ready.dev/agents-json-validator)
- [/agent-permissions-validator](https://agent-ready.dev/agent-permissions-validator)
- [/agent-readability-score](https://agent-ready.dev/agent-readability-score)

Hub guide for AI agents looking to summarise or cite Agent Ready as a whole:

- [/complete-guide-to-agent-readability](https://agent-ready.dev/complete-guide-to-agent-readability) — what agent readability is, why it matters, the three layers (discovery / extraction / protocols), and a prioritised fix sequence linking to every validator above.

## Usage

### Scan via the website

Visit [agent-ready.dev](https://agent-ready.dev), enter a URL, and get results in seconds.

### Embed a badge

After scanning, copy the badge markdown from the results page:

```markdown
[![Agent Ready](https://agent-ready.dev/api/badge/your-domain.com)](https://agent-ready.dev)
```

### Public scan endpoint (no auth)

```bash
curl -X POST https://agent-ready.dev/api/scan \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
```

Returns a JSON object with `scan` (full results) and `shareUrl` (shareable link).

### Authenticated API v1 (Pro / Team)

Pro subscribers issue keys from [/dashboard/api-keys](https://agent-ready.dev/dashboard/api-keys) and authenticate with `Authorization: Bearer ar_live_<prefix>_<secret>`. Three endpoints: `POST /api/v1/scans` (async 202 + poll), `GET /api/v1/scans/{id}`, `GET /api/v1/scans?limit=N`. Full reference at [/docs/api](https://agent-ready.dev/docs/api); OpenAPI spec at [/api/v1/openapi.json](https://agent-ready.dev/api/v1/openapi.json).

### MCP server

Same API key, MCP transport at `POST https://agent-ready.dev/api/v1/mcp`. Exposes `scan_site` and `get_scan` tools. Server Card at [/.well-known/mcp.json](https://agent-ready.dev/.well-known/mcp.json), OAuth metadata at [/.well-known/oauth-protected-resource](https://agent-ready.dev/.well-known/oauth-protected-resource).

### CI/CD integration

Composite GitHub Action: `uses: mlava/agent-ready@v1`. Posts PR comments with scores; fails the workflow when the Vercel score regresses below a configured threshold.

## Configuration

No configuration needed. Agent Ready is a hosted service at agent-ready.dev.

The scanner uses the user agent `agent-ready-scanner/1.0 (+https://agent-ready.dev)` and respects robots.txt directives.

## Check Reference

### Site-wide checks (S1-S15)

- S1-S4: llms.txt existence, content-type, non-empty, URL format
- S5-S7: robots.txt AI bot allowance, /llms.txt access, existence
- S8-S9: sitemap.xml validity, lastmod dates
- S10-S11: sitemap.md existence, structure
- S12-S13: AGENTS.md existence, required sections
- S14-S15: HTTPS, root OpenAPI spec (API-first sites)

### Per-page checks (P1-P23)

- P1-P4: HTTP status, redirects, content-type, x-robots-tag
- P5-P9: Canonical link, meta description, og:title, og:description, lang
- P10-P11: JSON-LD presence, required fields
- P12-P14: Heading count, text-to-HTML ratio, glossary link
- P15-P20: Markdown mirror, frontmatter, alternate link, Link header, content negotiation, sitemap section
- P21-P22: Code block language tags, API schema links
- P23: JS rendering dependency (static HTML contains rendered text)

### llmstxt.org checks (L1-L10)

- L1-L3: File accessible, H1 present, valid markdown (required, 3x weight)
- L4-L6: Blockquote summary, H2 sections, link format (recommended, 1x weight)
- L7-L9: Links accessible, optional section, content-type (recommended, 1x weight)
- L10: llms-full.txt available (optional, 0.5x weight)

### Protocol checks (C1-C7)

- C1-C3: MCP Server Card exists, required fields, OAuth Protected Resource metadata
- C4-C5: A2A Agent Card exists, required fields
- C6: Wildcard agents.json manifest (API-first sites)
- C7: agent-permissions.json manifest