# agents.md — AgentLens

What an agent may do on this site, and how to do it without guessing.

## What this site is

AgentLens scans websites for AI-agent readiness (a static pre-check — evidence
about a surface) and audits products with real agent runs (a measurement of
behaviour, self-serve at /audit). Treat the two differently: only the audit
measures what agents actually do.

## Endpoints you may call

| Method | Path | Purpose |
|---|---|---|
| POST | /api/scan | Run a pre-check. Body: {"url": "https://example.com"}. ~10s. |
| GET | /api/score/{domain} | Stored result for a domain. |
| GET | /api/badge/{domain} | SVG badge with the scan score and grade. |
| GET | /api/leaderboard | Ranked domains from the static pre-check. `?category=` filters. |
| POST | /api/mcp | MCP server (streamable HTTP, no auth): scan_domain, get_score, get_leaderboard, get_skill, create_audit_plan. |

## MCP

    claude mcp add --transport http agentlens https://agent-chi-lime.vercel.app/api/mcp

Advertised at /.well-known/mcp.json. The fix-loop playbook is /skill.md (also
the `get_skill` tool). Rate limits: 60 MCP calls/min/IP, 20 scans/min shared.
| POST | /api/waitlist | Join the journey/monitor waitlist. Body: {"email", "domain?", "source"}. |
| GET | /api/openapi.json | The full contract for everything above. |

## Rules

- Rate limit: 10 scans/minute/IP (429 with `retry_after_s` when exceeded).
- No authentication is required for scanning. Do not scan domains you have no
  reason to evaluate; results are public.
- Errors are JSON: {"code": "...", "message": "...", "next_action": {...}}.
  Branch on `code`; `next_action` is a request you can make verbatim.

## Recovery example

GET /api/score/unscanned.com → 404:

    {"code": "DOMAIN_NOT_SCANNED",
     "message": "unscanned.com has not been scanned yet.",
     "next_action": {"method": "POST", "endpoint": "/api/scan",
                     "body": {"url": "https://unscanned.com"}}}

Follow the next_action, then retry your original request.

## Base URL

https://agent-chi-lime.vercel.app