Data Quality and Agent Readiness: Why Structured Responses Win
When an AI agent calls your API and gets back an HTML error page, the interaction is over. The agent cannot parse it, cannot retry intelligently, and cannot tell its user what went wrong. D6 Data Quality measures whether your business speaks the language agents understand — structured, typed, consistent JSON.
The Problem: Agents Cannot Read Your Error Pages
Humans see a 404 page and understand what happened. The page has a friendly message, maybe a search bar, maybe a link back to the homepage. AI agents see the same page and get a wall of HTML tags, CSS classes, and JavaScript. They cannot extract the one piece of information they need: what went wrong and what to do next.
After scanning 500 businesses, we found that the majority return HTML error responses on their API-like endpoints. Of the 199 businesses scoring below Bronze (under 40), over 80% serve HTML on error paths. Among the 52 Silver-tier businesses (60-74), every single one returns structured JSON errors with consistent codes.
The pattern is unmistakable: data quality is a reliable predictor of overall agent readiness. If a business returns structured data, it almost certainly has the other fundamentals right too — because structured responses require the same engineering discipline as good APIs, proper auth, and reliable infrastructure.
Three Tiers of Response Quality
Not all data quality failures are equal. We see three distinct tiers when agents interact with business endpoints. Each tier produces dramatically different agent behavior — from complete failure to seamless automation.
HTML Error Page
D6: 0-5 ptsReturns a full HTML page with a styled 404 template. Agents cannot parse the error type, reason, or whether the resource exists elsewhere. This is the most common response from the 199 businesses scoring below Bronze.
Response: <html><body><h1>404 Not Found</h1><p>The page you are looking for...</p></body></html>
Unstructured JSON
D6: 15-30 ptsReturns JSON but without consistent keys or error codes. Agents can detect it is JSON, but every endpoint uses different field names. One returns "msg", another "message", a third "error_description". Agents need consistency across all endpoints.
Response: {"msg":"not found"}
Structured JSON Envelope
D6: 70-100 ptsReturns consistent JSON with error codes, human-readable messages, and request tracing. Every endpoint follows the same envelope shape. Agents learn the pattern once and can handle any response from any endpoint predictably.
Response: {"error":"Not found","code":"NOT_FOUND","request_id":"req_abc123"}
The structured JSON envelope is the gold standard. When an agent receives {"error":"Not found","code":"NOT_FOUND","request_id":"req_abc123"} it knows exactly what happened, can log the request ID for debugging, and can branch its logic based on the error code. A NOT_FOUND might trigger a search fallback. An UNAUTHORIZED triggers a re-authentication flow. An HTML page triggers nothing but confusion.
What D6 Data Quality Actually Measures
The AgentHermes scanner checks six aspects of data quality. Each contributes to the D6 sub-score, which carries a 0.10 weight in the overall Agent Readiness Score.
JSON-LD: The Bridge Between SEO and Agent Readiness
JSON-LD schema markup is the highest-leverage D6 improvement most businesses can make. It is the same structured data that powers Google rich results, but AI agents extract far more from it than search engines do. When an agent visits your homepage and finds Organization markup, it immediately knows your business name, address, hours, contact info, and social profiles — without scraping a single HTML element.
The OpenAPI specification tells agents what your API can do. JSON-LD tells agents what your business is. Together, they give an agent the complete picture: identity plus capability.
Of the 500 businesses we scanned, fewer than 15% have any JSON-LD markup at all. Among those that do, the most common types are Organization and LocalBusiness. Product and Offer markup — the types that actually let agents read pricing and availability — appear on fewer than 5% of all businesses scanned.
The Agent-Readable Minimum
At minimum, every business should have JSON-LD Organization markup on the homepage with name, url, logo, contactPoint, and sameAs (social links). Service businesses should add Service markup with serviceType, provider, and areaServed. E-commerce should add Product and Offer with price, priceCurrency, and availability. This is the structured data floor that separates “agent-visible” from “agent-invisible.”
The Envelope Pattern: One Shape for Every Response
The top scorers in our dataset all follow what we call the envelope pattern. Every successful response wraps data in a consistent outer shape. Every error uses the same error shape. The agent learns the pattern once and can parse any endpoint without custom logic.
Here is what the pattern looks like in practice. Resend (the only Gold-tier business at 75) uses it. Stripe (Silver, 68) uses it. Vercel (Silver, 70) uses it. Every company in our top 30 uses some variation of it.
Success Envelope
{
"data": { ... },
"meta": {
"request_id": "req_abc123",
"timestamp": "2026-04-15T...",
"pagination": {
"total": 142,
"has_more": true,
"cursor": "cur_xyz"
}
}
}Error Envelope
{
"error": "Resource not found",
"code": "NOT_FOUND",
"request_id": "req_abc123",
"details": {
"resource": "product",
"id": "prod_missing"
}
}The key principle is one envelope, every endpoint. When an agent interacts with 20 different endpoints on your API, it should never need to guess the response shape. The same top-level keys appear everywhere. The same error code vocabulary is shared across all endpoints. The request_id field appears in every response so the agent can reference specific interactions when reporting issues or debugging failures.
How to Improve Your D6 Score
Four changes ordered by impact. The first two can be done in an afternoon.
Add JSON-LD Organization markup to your homepage
Include name, url, logo, contactPoint, address, and sameAs. This is a single <script type="application/ld+json"> tag. Copy a template, fill in your details, paste it into your page head. 30 minutes, biggest single D6 improvement.
Replace HTML error pages with JSON on API routes
Every route that an agent might call should return JSON errors with a code field. Most frameworks have error middleware that catches unhandled errors and formats them. Express: app.use(errorHandler). Next.js: middleware.ts. Django: custom exception handler.
Standardize your response envelope
Pick one shape for success (data + meta) and one for errors (error + code + request_id). Document it in your OpenAPI spec. Enforce it with middleware so no endpoint can return a raw, unwrapped response.
Add Product and Offer markup for pricing
If you sell products or services, Product + Offer schema markup lets agents read your pricing without hitting an API. Include name, description, price, priceCurrency, and availability. This lifts both D6 Data Quality and D4 Pricing.
Data Quality in Practice: Gold vs Below-Bronze
Resend (Gold, 75)
Every API endpoint returns JSON with consistent error codes. Error responses include a machine-readable code, human message, and request ID. JSON-LD Organization markup on the marketing site. Full OpenAPI spec with typed response schemas for every endpoint.
Stripe (Silver, 68)
Industry-standard error envelope with type, code, message, and param fields. Every error is documented in the API reference with the exact JSON shape. Consistent pagination with has_more and cursor. Content-Type headers always correct.
Typical Local Business (12-25)
No JSON-LD markup. Contact page is a form, not structured data. 404 page returns the full website HTML template. No API endpoints at all. Business hours embedded in a footer div, not machine-readable. Agents extract nothing.
Typical SaaS (35-50)
Has an API but error responses mix formats. Some endpoints return JSON errors, others return HTML. No consistent error codes — "invalid" on one endpoint, "bad_request" on another. No request IDs. Partial JSON-LD (Organization only, no Product).
The gap between Gold/Silver and below-Bronze is not about having advanced AI features. It is about engineering fundamentals. Consistent response formats, proper headers, machine-readable markup. These are the same things that make APIs pleasant for human developers — agents just require them to function at all. A human developer can read an HTML error page and figure it out. An agent cannot.
Frequently Asked Questions
What is D6 Data Quality in the Agent Readiness Score?
D6 Data Quality is one of 9 dimensions in the Agent Readiness Score, carrying a weight of 0.10 (10%). It measures whether your business returns structured, consistent, machine-readable data that AI agents can reliably parse and act on. This includes JSON-LD schema markup, consistent API response envelopes, proper Content-Type headers, and typed error responses.
Why do HTML error pages hurt my score?
When an AI agent sends a request and receives an HTML error page, it cannot programmatically determine what went wrong. Was the resource not found? Did the request fail authentication? Is the service down? An HTML page designed for human eyes is opaque to agents. A structured JSON error with a code field like NOT_FOUND or UNAUTHORIZED lets the agent handle the failure and try a different approach automatically.
What is a JSON envelope pattern?
A JSON envelope is a consistent response wrapper used across all API endpoints. Every successful response uses the same top-level shape (e.g., { "data": ..., "meta": ... }) and every error uses the same error shape (e.g., { "error": "message", "code": "ERROR_CODE", "request_id": "..." }). Agents learn the envelope once and can parse any response from any endpoint without per-endpoint logic.
How does JSON-LD schema markup help AI agents?
JSON-LD (JavaScript Object Notation for Linked Data) embeds structured data into HTML pages using schema.org vocabulary. When an agent visits your website, it can extract Organization info, Product details, pricing via Offer markup, business hours, and service descriptions — all in a machine-readable format. This is the same markup that powers Google rich results, but AI agents use it for deeper understanding than search engines do.
What is the fastest way to improve my D6 score?
Three changes with the highest impact: (1) Add JSON-LD Organization and Product/Service schema markup to your homepage — this takes 30 minutes with a template. (2) Ensure all API endpoints return JSON with consistent error codes instead of HTML error pages. (3) Set correct Content-Type: application/json headers on all API responses. These three changes can move D6 from 10 to 60+ in an afternoon.
See your D6 Data Quality score
Run a free Agent Readiness audit to see how your data quality stacks up across all 9 dimensions. Find out if agents can read your responses — or if they are hitting a wall of HTML.