Your Agent Is Reading a Different Design System | Rachel Cantor

Skip to content

- BACK

When an agent tried to build two components from scratch instead of referencing what I thought was my well-documented design system, I went looking for the point where the MCP had stopped seeing my docs. The guidance was sitting in a field the Storybook MCP manifest never reads, so as far as the agent was concerned it had never been written.

I fixed it. What stayed with me was that I only caught it because I happened to be looking. Nothing in the pipeline flagged anything. It built cleanly, served a manifest, and answered the agent’s question with a confident, incomplete answer. It would have done the same thing the next time. And I had no way to know how many components were already invisible to it.

So I built a Storybook addon that checks each component for the gaps that leave an agent guessing. It’s called Oversight. The source is on GitHub, and there’s a live demo.

TL;DR : Oversight is a Storybook addon that lints the components manifest, the file get-documentation reads to answer your agent. It flags failed docgen extraction, the wrong docgen extractor, undocumented required props, missing component descriptions, and dangling redirect links. Findings show up per component while you work. It does not write your docs for you. It tells you when the pipeline dropped them.

What the agent actually reads

Your Storybook dev server generates a JSON file at /manifests/components.json, built from your stories and your component source. That file is the only thing the MCP server reads. When an agent asks get-documentation about your Button, the answer is assembled from the manifest. Not from your source. Not from your Docs tab.

So the first question about any component’s documentation is whether the manifest has it.

The manifest is a preview feature, and Storybook is explicit that its schema is not a public API. Which is the argument for checking your manifest instead of trusting it. Everything here was tested against Storybook 10.5 in July 2026.

Why the guidance has to be prose

Selection guidance matters more to an agent than usage guidance. An agent that can’t tell which component to reach for builds a new one. I wanted a structured way to hand it that judgment, so I started designing a custom JSDoc tag to hold it. Something greppable. Something a lint rule could validate.

Then I checked what get-documentation actually returns. Component-level JSDoc tags aren’t in it. Not a custom tag, not @deprecated, not anything. The description it hands the agent is tag-stripped prose, under both extractors.

Which means every component you have ever deprecated is, as far as your agent knows, current. The tag is right there in the manifest. It just never makes it into the answer.

So a custom tag would have been exactly as invisible to the agent as parameters.docs.description.component had been.

What get-documentation does return, verbatim, is the component description. So the guidance has to live there, as a plain sentence with a real link in it:

/**<br>* A committed-selection box: tick one or more items and submit them together,<br>* rather than applying each change the moment it flips.<br>* For a setting that applies the moment it flips, use<br>* [Toggle](?path=/docs/forms-toggle--docs) instead.<br>*/<br>Copy

That’s a redirect: a markdown link inside a component’s description that points at a different component’s docs page. Its target is a manifest ID, which means it can rot. A redirect that points at a component you renamed six weeks ago is worse than no redirect, because it reads like an answer.

What it checks

Oversight lints the documentation the MCP consumes, and the pipeline that decides whether the MCP ever sees it.

Most of what goes wrong goes wrong in the extractor, more commonly called a documentation generator, or docgen. It reads your component’s TypeScript and turns your props and JSDoc into the structured data the manifest is built from. Storybook ships two of them, and they do not agree.

docgen-missing (error): the manifest entry has no docgen payload at all. Extraction failed outright, and your agent is looking at a component with no props.

extractor-drift (warning): react-docgen is the default. It reads the source file directly and never runs the type checker, which makes it fast and means it can only see what’s written in front of it. A prop type assembled out of other types, declared elsewhere, is a name it can’t resolve. That’s exactly what my design system’s Button uses, so react-docgen returns nothing rather than guessing and every prop description comes back blank. react-docgen-typescript runs the real TypeScript compiler and resolves those types the same way your editor does. So I set reactDocgen: 'react-docgen-typescript' in .storybook/main.ts and moved on.

The problem is that a setting can change without anyone noticing it changed. Someone edits main.ts. Storybook falls back. The prop descriptions stop...