AIO Score

Agent Input Optimization — a single number (0–100) that tells you how well an AI agent can read a given URL.

What it measures

The AIO Score predicts the likelihood that an LLM consuming this page will produce accurate output. Higher score = more semantic signal per byte, less framework noise, better content negotiation, lower hallucination risk. The same engine powers the public scanner at buildonto.dev/api/aio, the authenticated POST /v1/score endpoint, and the score shown on /serve/dashboard.

Scoring model

ℹ

Subtractive penalty model, not a weighted average. Every URL starts at 100. Each detected issue subtracts points; each detected positive signal can also add a benefit row but doesn't raise the score above the penalty result. Final score is the plain subtraction.

Result shape from the scoring engine:

{
  score: 92,                       // 0–100, after all subtractions
  grade: 'Excellent',              // bucket name
  hallucination_risk: 'low',       // low | medium | high
  insights: { ... },               // boolean flags per signal
  penalties: string[],             // each is a -N point line item
  benefits:  string[],             // positive signals detected
  recommendations: [               // ranked, high-priority first
    { priority: 'High', title: '...', description: '...' }
  ],
  stats: { raw_size, efficiency, ... },
  bot_preview: '...',              // first 200 chars of cleaned Markdown
}

Grade ranges

Score	Grade	Hallucination risk
80–100	Excellent	low
60–79	Good	low
40–59	Needs work	medium
20–39	AI-hostile	high
0–19	Invisible	high

Signals checked

Signal	Penalty when missing/bad
Semantic HTML (h1/h2/h3 hierarchy, paragraphs)	−15 if hierarchy broken / no h1
JSON-LD schema markup	−10 (no penalty when SDK injects it)
Content negotiation (text/markdown serving)	−15 if site doesn't honor Accept header
robots.txt allows AI crawlers	−30 if GPTBot disallowed
Reasonable signal-to-noise ratio	−5 to −20 scaled by React Tax
No WAF block on Onto-Reader	−25 if site returns 403/401
Markdown payload smaller than HTML	−10 if extraction yields no reduction
Page is reachable (200 OK)	score = 0 if URL unreachable

How to improve

The fastest single move: install @ontosdk/next. The SDK serves clean Markdown to bots (negotiation penalty resolved), preserves semantic structure (heading penalty resolved), and reports its presence so the scorer sees the integration. Sites running the SDK typically jump 30–50 points without any content changes.