# JSON for MCP, Markdown for LLM

> The Indeed benchmark, read correctly.

Published 2026-08-07.

The most repeated stat in machine-readable design systems is "JSON is five times cheaper than Markdown." It comes from real work, it points somewhere true, and it's the wrong lesson. The right lesson is smaller, sharper, and more useful: structure beats size, and different kinds of knowledge want different formats.

The work behind the headline deserves to be described accurately, because it's the best practitioner research this niche has. Diana Wolosin, with Tony Rucker building the MCP infrastructure, ran an actual benchmark instead of a vibes test: 77 components parsed from their documentation, eight different MCP configurations, 1,056 prompts, measured on token cost and accuracy. Not a demo. A methodology.

What they found: their human-written documentation was verbose, around 30,000 tokens a query, and structured JSON beat it badly on both cost and accuracy. That's where the "five times cheaper" line comes from, and as far as it goes, it's real.

But Wolosin's actual operating rule is the part worth tattooing somewhere: JSON for MCP, Markdown for LLM. Structured component data (props, sizes, variants, allowed values) belongs in JSON, because it's a contract, and contracts want schemas. Natural-language rules, guidance, and reasoning still belong in Markdown, with front matter instead of bloat, because prose is what language models read with the highest fidelity. The benchmark didn't crown a format. It drew a boundary between two kinds of knowledge.

Get that boundary wrong in either direction and you pay for it.

Cram everything into JSON and you've built a data structure that can't explain itself. "When the user's action is destructive, use the danger variant" is a rule with a when in it. Flatten it into a schema and you either lose the condition or invent a brittle mini-language nobody, human or machine, reads reliably. Judgment serialized as data stops being judgment.

Keep everything in Markdown and you've built documentation that has to be reinterpreted on every single query. Your Button's props are facts. Wrapping facts in paragraphs means paying an interpretation tax every time, at 30,000 tokens a pass, with a nonzero error rate on each interpretation. That's what Indeed measured, and the tax was brutal.

The sorting question I use: is this a contract or is it guidance? Does it validate, or does it advise? Props, variants, token values, allowed combinations: contract, JSON, served over MCP so agents query it deterministically. Usage philosophy, accessibility reasoning, do-this-not-that: guidance, Markdown, loaded as context. If a sentence contains "always" or "never," it's probably trying to be a contract. If it contains "usually" or "prefer," it's guidance and should stay prose.

Two honest caveats, because the people closest to this work carry them and so should we. First: this is one team's numbers on one design system. Treat it as direction, not law. Your components, your docs, your ratios. The boundary principle transfers; the multiplier may not. Second: structure raises the floor, it doesn't remove the ceiling. When Indeed's winning format met production reality, the team generated 4,300 prototypes in four months, and an audit of a sample still found typography violations, broken spacing, and a color palette nobody approved. Machine-readable is necessary. It is not sufficient. Governance and review stay in the loop.

What this means for a team of any size, starting Monday: pick your three most-used components. Write their contracts as JSON: props, variants, tokens, nothing editorial. Move the editorial voice into a lean Markdown file beside them. Serve the JSON through an MCP server if you have one, or just put both where your agent's context loads from if you don't. Then run the cheap version of Indeed's test: same twenty prompts against the old docs and the new split, and count what breaks. You'll have your own multiplier by Friday, and your own multiplier beats anyone's headline.

The free starter kit at tokenstoagents.ai/kit includes the contract-vs-guidance checklist plus a component contract template to copy.