Agent-Readiness Audit Scoring
Hunch's free agent-readiness audit scans the public pages of your website and reports how readily AI agents can discover, read, and operate it. This page documents exactly how the score is calculated, what is graded and what is not, and every machine-readable way to retrieve a report.
The canonical version of this document lives at hunchbank.com/methodology. Machine agents can request GET /api/v1/methodology as Markdown.
What one audit run does
The scan starts at the URL you submit, follows internal links, reads sitemap.xml where present, and fetches a bounded set of distinct pages. Pages that serve empty shells to plain HTTP fetches are re-fetched through browser rendering when available. Each report records which scan mode ran:
| Scan mode | Meaning |
|---|---|
multi_page_static | All pages were fetched without a rendered browser |
browser_rendered_multi_page | At least one page required browser rendering |
Every report is a snapshot of one public URL at one point in time. Rescanning replaces the stored result with fresh evidence while keeping stable share URLs, so you can compare progress over time.
One score, three buckets
A single bucketed model produces everything published: the 0–100 readiness score, the ready / partial / not_ready band, and the A–F letter grade. There are no separate hidden computations.
score = round(earned ÷ applicable × 100) + min(bonus, 5) // clamped to 0–100
Scoring version: readiness-20260821a (reported as scoringVersion in the API response).
Essential checks (graded on every public site)
| Check | Points | Earned when |
|---|---|---|
| robots.txt present | 6 | A robots.txt exists |
| sitemap.xml discoverable | 6 | Sitemap referenced or found |
| AI crawlers not blocked | 8 | No GPTBot/ClaudeBot/etc. blocked in robots.txt (no robots.txt at all counts as open by default) |
| Server-rendered content | 10 | Content visible without JavaScript execution |
| Heading structure | 5 | Average ≥ 3 headings per scanned page (≥ 1 earns partial credit) |
| Readable text depth | 5 | Average ≥ 5 paragraphs per page (≥ 2 earns partial credit) |
| Strict-Transport-Security header | 4 | Header present on the homepage response |
| Content-Security-Policy header | 4 | Header present |
| X-Content-Type-Options header | 4 | Header present |
| X-Frame-Options header | 4 | Header present |
| Form labeling quality | ×14 | Proportional: labeled fields ÷ typed inputs × 14. Excluded if the site has no form inputs |
| Button text quality | ×10 | Proportional: descriptive buttons ÷ all buttons × 10. Excluded if the site has no buttons |
Essential checks can reach ~80 points; the exact denominator depends on which control classes exist (see N/A exclusion below).
Recommended checks (activate only on evidence)
Recommended checks apply only when the scan finds evidence the surface exists. A site is never penalized for an interface it does not offer — non-applicable checks drop out of the score denominator entirely.
| Check | Points | Gate | Earned when |
|---|---|---|---|
| Booking/contact path identifiable | 6 | Site has forms, buttons, or detected intent surfaces | Scan identifies a booking flow or contact/lead-capture path |
| Pricing intent identifiable | 4 | Same gate | Scan identifies pricing/plan/quote content |
| Support & checkout surfaces | 2 | Same gate | 1 point each for support surfaces and checkout paths |
| Schema.org potentialAction | 4 | Site publishes structured data | potentialAction metadata exposes callable workflows |
| Agent protocol files | up to 4 | At least one protocol file responds | 1 point per file found: .well-known/ai-plugin.json, .well-known/mcp.json, openapi.json, agents.json, .well-known/agent-card.json |
Worked example: a documentation site with no forms and no buttons never loses points for "missing booking flow" — the workflow-surface checks simply do not apply. Its grade reflects only the checks that mean something for its kind of site.
Bonus pool (capped at +5, absence never lowers the score)
| Signal | Points |
|---|---|
| MCP presence mentioned on site | +2 |
| llms.txt published for agents | +3 |
| Trust signals present | +2 |
| Content reachable via rendered browser | +2 |
The bonus total is capped at five points. Emerging formats earn extra credit but chasing them can never dominate the score.
Grades from the same number
Score, readiness band, and letter grade all derive from one value:
| Score | Band | Letter grade |
|---|---|---|
| 90–100 | Ready | A |
| 70–89 | Ready | B |
| 50–69 | Ready | C |
| 25–49 | Partial | D |
| 0–24 | Not ready | F |
Form operability: the second axis
A readiness score cannot tell you whether an agent could actually complete your booking form. Every captured form also receives four static verdicts (scoring version operability-20260817a):
| Verdict | Meaning |
|---|---|
| Callable | Not unsafe, and no required fields the scan cannot resolve |
| Fillable | Every required field resolvable via label text, aria-label, placeholder, or semantic name |
| Submittable | A visible submit control exists |
| Safe | No payment fields, passwords, or file uploads exposed without an explicit approval gate |
Per-form verdicts combine into a site-wide operability score out of 100. Two deliberate rules: forms whose action targets another origin report unknown rather than being penalized (submission outcomes there are unobservable), and honeypot fields plus hidden CSRF tokens count as sane defaults to skip, not failures.
The operability probe is static analysis. It predicts what an agent would face — it never submits real forms on your site.
Reading your report
Every report includes:
- The score, band, letter grade, and a plain-language summary
scoreBreakdown: every check with its bucket, points earned, maximum, and whether it applied- Per-form operability verdicts with unresolved-required-field and safety details
- Prioritized recommendations tied to what the scan actually observed
Start with failed Essential checks — they describe the baseline any agent needs. Then review Recommended gaps that match what your product actually offers.
Machine access
Reports are machine-readable at the same canonical resource. Everything below is public, read-only, and requires no credentials. None of these interfaces starts a scan or touches the target site.
# Latest completed report as JSON
curl https://api.hunchbank.com/api/v1/report?url=https://example.com
# Same URL as compact Markdown for agents
curl -H "Accept: text/markdown" \
https://api.hunchbank.com/api/v1/report?url=https://example.com
# OpenAPI description and API catalog
curl https://api.hunchbank.com/openapi.json
curl https://api.hunchbank.com/.well-known/api-catalog
# Official CLI (retrieves completed reports)
npx hunch-audit example.com
npx hunch-audit example.com --json
Additional discovery surfaces:
| Resource | URL |
|---|---|
| Methodology as Markdown | GET https://api.hunchbank.com/api/v1/methodology |
| AI catalog | https://api.hunchbank.com/.well-known/ai-catalog.json |
| MCP server manifest | https://api.hunchbank.com/server.json |
MCP clients can pull the same report with the read-only site.get_audit_report tool on any Hunch connector.
Errors use RFC 9457 application/problem+json with stable codes (invalid_url, no_report, storage_unavailable). The public endpoint permits 1000 requests per client per 60 seconds (RateLimit-Policy: 1000;w=60); 429 responses include Retry-After.
Limits
- A report describes evidence available from one public URL at one time. Status codes, rendered content, and advertised interfaces change after the snapshot.
- Private pages, authenticated workflows, paywalls, bot defenses, geographic differences, and user-specific state cannot be observed from a public scan.
- The simulated conversation shown in reports is generated from scanned page evidence — not a recording of a live agent run.
- JavaScript-heavy single-page apps render best-effort via browser rendering; client-only surfaces may still be missed.
- The operability probe is static analysis and never submits real forms.
- A score is not a security, accessibility, privacy, legal, or compliance certification. Each requires its own dedicated review.
Use the audit as a prioritized technical review with evidence attached — then fix what it found. That last step is what Hunch is built for.