5 proven Claude + Hygraph MCP workflows that actually save you time

Machine-readable content: why AI misreads your website

AI misreads websites that store facts as page layout. See what machine-readable content is and how to structure facts AI can read without guessing.
Jing Li

Written by Jing 

Nov 20, 2026
Machine-readable content: stop mixing facts with layout

A customer asks an AI assistant how much your premium plan costs. The price lives in a PDF from last spring, next to an older price in a footnote, and the assistant picks the wrong one. Nothing about the answer sounds unsure. A person reading the PDF would have known which price was current, but to the assistant it was just noise.

Most websites store facts as layout. The price is bold text under a heading, and the return policy is a paragraph that three pages copied. People read that without thinking twice. AI has to guess, and it does so with confidence. In our view, the fix belongs at the source: store each fact as data software can read directly, so AI no longer has to interpret your pages. This guide shows what that looks like and how to get there.

#What is machine-readable content?

Machine-readable content is content stored as labeled, typed and connected fields that software can parse, query and act on without interpreting a page. A price is a number in a price field, a date is a date, and a related product points to that product's entry instead of repeating its name.

It builds on structured content, which breaks content into reusable pieces. Machine-readability adds one more question: can software use those pieces on its own, without anyone explaining what they mean?

#Machine-readable vs human-readable content

People read context. We see a bold number under "Pricing" and know it's the price. Software sees a string of characters. Human-readable content relies on layout and wording to carry meaning, while machine-readable content puts that meaning into the structure itself.

Human-readable Machine-readable
Where the meaning lives Layout, headings and wording Field names, types and relationships
Example "Our Pro plan costs $49 per month, billed yearly." plan: Pro, price: 49, currency: USD, billing: yearly
What software does with it Guesses from the text Reads the value directly
When it changes Every copy needs editing One field updates everywhere it's used

Good content serves both. The same entry can render as a readable page for people and as clean data for software.

#Why AI misreads your website

For years, machines read your website to index it for search. Now AI assistants, AI search and agents read it to answer questions, often without anyone seeing the page the answer came from. When a fact only exists as layout, they have to work out what it means, and that's where most wrong answers start.

1. Facts that only make sense visually

The current price is the big number in the banner, and the old price is crossed out next to it. Once the styling is stripped away, both are just numbers on a page, and AI has to decide which one counts.

2. Facts locked in files and images

Price lists in PDFs, specs in slide decks and opening hours in an image hold facts that software can't reliably read. Even when it can read them, it has no way to tell whether the file is the current version.

3. The same fact in several places

Every copy of a fact is a chance for it to drift. Update the warranty period on the product page, miss it on the FAQ and two partner sites, and AI now has four answers to choose from.

4. Relationships written as words

"See the return policy above" or "works with the Pro model" only makes sense on the page where it's written. Once AI pulls that sentence into an answer, the link to the policy or the product is gone.

That guessing shows up in real answers. When the EBU and BBC tested four AI assistants on more than 3,000 news questions, 31% of responses had serious sourcing problems, with missing, misleading or incorrect attributions. That was with well-published news. A website that stores its facts as layout gives assistants even less to go on.

#What makes content machine-readable

1. Named, typed fields

Every piece of information software might need gets its own field, with a clear name and a type such as a number, a date, a yes/no value or a reference. A price stored as a number can be compared, sorted and checked. If the price sits inside a paragraph, software has to guess.

2. Stable IDs and references instead of copies

Each entry has an ID that stays the same when its title or URL changes. When one piece of content relates to another, it points to it by reference instead of repeating it. Change the source once, and every place that uses it stays correct.

3. Structured rich text instead of HTML strings

Long-form text needs structure too. Rich text stored as structured data keeps headings, links and embedded entries as elements software can recognize. An HTML string mixes content with presentation, so software has to untangle them first.

4. Metadata and taxonomy that carry meaning

Tags, categories, locales and audiences tell software what an entry is about and who it's for. Shared taxonomy also connects content across teams. A help article and a live status record that use the same tag can be found with one query, even if two different teams own them.

5. Validation at the source

Required fields, allowed values and formats are enforced when someone creates the content, so incomplete or malformed entries never reach your API.

6. An API software can query

Even well-structured content needs a way out. A query API, such as GraphQL, lets software ask for exactly the fields it needs and get predictable answers back. Software can also read the schema to discover what content exists.

7. Lifecycle fields that show what's current

Structure doesn't stop content from going out of date. A typed price field from last year is perfectly readable and completely wrong. Add valid-from and valid-until dates, a status such as draft, published or retired, and a last-reviewed date, so software can tell what's current and what's retired.

#Examples of machine-readable content

Not machine-readable Machine-readable
A price list in a PDF A product entry with price, currency and valid-from fields
An FAQ written as one long block of text Separate question and answer fields for each item
"The event takes place next Thursday at 3 pm" A date-time field with a time zone
"See the return policy above" A reference to the return policy entry
A store's opening hours in an image Opening hours as structured fields for each day
The same product description pasted into five sites One description entry that all five sites reference

Most teams have far more of the left column than the right. That content is still raw material, though, and you don't have to rebuild it by hand.

#How to make your content machine-readable

  1. List the questions software will ask. Start from real use cases, like "What does this cost?", "Is it in stock?" or "Which return policy applies in Germany?" Each answer is a candidate field.

  2. Find the facts stuck in layout. Look for information locked in PDFs, images and long text blocks, facts copied into several places, and pages nobody has updated in a long time.

  3. Model a typed field for each answer. Give every answer from step 1 a clear name and type. Our content modeling guide covers how to approach it.

  4. Bring your existing content into the model. Most content worth keeping already exists in PDFs, Word files and Google Docs, and nobody wants to retype it. You can point an AI assistant at a document through the Hygraph MCP Server, ask it to propose how the document maps to your models, and check that proposal before it writes anything.

  5. Replace copies with references. Wherever the same information appears twice, keep one source and point to it.

  6. Add metadata and taxonomy. Agree on shared tags and categories across teams, so the same concept has the same name everywhere.

  7. Validate at the source. Make the important fields required and restrict values where you can.

  8. Expose it through an API. Make the content queryable, so software asks for the fields it needs instead of scraping your pages.

#Separate facts from layout

Every fact on your website that only exists as layout is a fact AI has to guess. Moving those facts into typed, connected fields is the most direct way to stop AI from misreading your site.

Deciding what AI may do with that content, and who answers for the result, is a question for the whole team. Bohdan Zatirko, our Principal Solutions Architect, covers that side in our guide to AI-ready content.

Want to see machine-readable content in practice? Start for free on Hygraph, the agentic content platform and headless CMS, and build your first content model.

Frequently Asked Questions

Blog Author

Jing Li

Jing Li

Jing is the Organic Growth Lead at Hygraph. Besides telling compelling stories, Jing enjoys dining out and catching occasional waves on the ocean.


Share with others

Sign up for our newsletter!

Be the first to know about releases and industry news and insights.