All articles
November 21, 2026

How to Audit Your Docs with an AI Agent

audit-docs-with-ai-cover.png

With DocStar, you can audit your whole docs site with an AI agent in one prompt: connect Claude Code, Cursor or Codex to the DocStar MCP, ask it to find gaps, outdated pages and broken links, and it reads every page, reports what it found, and saves each fix as a draft for you to review. Nothing goes live until you publish it.

Most docs teams know their docs have problems. They just never find the afternoon to read 80 pages side by side and list them. An AI agent connected to your DocStar workspace can do that reading for you, so the audit stops being a quarterly project and becomes a prompt you run whenever you ship.

#

Why docs audits never happen (and why it matters more now)

A manual docs audit means opening every page, checking it against the product, noting broken links, spotting duplicate answers and finding the topics nobody wrote. It is slow, boring and easy to postpone.

The cost of skipping it has gone up. Your docs are no longer read only by people. AI assistants read your pages through llms.txt and the Markdown copy of every page, and in DocStar an API collection's docs also power the MCP server that AI agents use to call your API. An outdated page now gives an AI assistant a wrong answer, not just a confused reader.

What goes wrong What it costs
A page describes an old screen or flow Support tickets from readers who followed it
Two pages answer the same question differently Readers and AI assistants pick the wrong one
A link points to a page that was removed Dead ends for readers and crawlers
A common question has no page at all Readers leave, or open a ticket
An API page is missing a field or example AI agents call your API with the wrong body
#

How to audit your docs with an AI agent in DocStar

This is the main path we recommend. You do the judgment calls; the agent does the reading and the first drafts.

#

1. Connect your AI assistant to DocStar

Add DocStar to Claude Code, Cursor, Codex, Claude or ChatGPT. If DocStar is in your assistant's connector directory, connect it from there. If not, add it as a custom (remote) MCP server with this URL:

https://mcp.docstar.io/mcp

The first time the assistant needs your workspace, you sign in to DocStar in your browser. There is no API key to copy. The assistant only sees the workspaces and collections your DocStar account can access, with the same permissions you have. See Connect your AI assistant.

#

2. Give it one audit prompt

Paste a prompt like this and change the collection name:

Use the DocStar MCP to audit our "Help Docs" collection. Read every page. Then give me a report with: (1) pages that look outdated or contradict each other, (2) links that point to pages that don't exist in the collection, (3) questions a new user would ask that no page answers, (4) pages that are too thin to be useful, and (5) API pages missing a description, a parameter or a full request example. Rank the issues by impact. Don't change anything yet; show me the report first.

[Screenshot: Coding agent showing its audit report for a DocStar collection]

#

3. What the agent does

With the DocStar MCP connected, the agent can find your collections and pages, read them, rewrite or fix them, rename pages and change their URLs, and publish when you say so. For an audit, that means it:

  • Lists every page in the collection and reads each one.

  • Compares pages with each other to find duplicates and contradictions.

  • Checks the links on each page against the pages that actually exist.

  • Notes topics that are mentioned but never explained.

  • For API collections, checks each endpoint doc for missing descriptions, parameters and examples.

  • If you point it at your code, compares what the docs say with what the code does.

You get a ranked list, not a pile of edits.

#

4. You decide, the agent drafts the fixes

Read the report and tell the agent what to fix:

Fix issues 1 to 6. Merge the two "Reset password" pages into one and point the old URL at it. Write a new "Getting started" page for the missing setup steps. Leave the pricing pages alone; I'll handle those.

DocStar is safe by design here. The agent shows you what it will create, change or publish and waits for your OK, and every edit is saved as a draft. Drafts never reach your live site or your MCP server. When a page's URL changes, DocStar redirects the old URL to the new one automatically, so merged or renamed pages don't create new broken links. See Redirects.

#

5. Review and publish

Open the drafts in DocStar, check the tone and the facts, and publish. Or ask the agent: "Publish the pages we fixed." If a change turns out wrong, every page keeps a Version History and a Published History, so you can preview an older copy and restore it.

The human's job: decide what matters, what stays private, how things are named and how they should sound. The agent's job: the reading, the comparing and the first drafts.

#

Add real reader signals to the audit

An agent can tell you what looks wrong. Your readers can tell you what actually hurts. DocStar's Analytics dashboard shows, for each page, how many times it was read, its SEO score, Yes and No votes from "Was this helpful?" and readers' written comments.

Before you run the audit:

  1. Open your collection and click Analytics.

  2. Set the date to Last Month and sort by Reads.

  3. Note the popular pages with many No votes, and copy a few of the comments.

Then add them to your prompt:

These pages get the most reads and the most "No" votes: [list]. Readers said: [comments]. Start the audit with these pages and tell me what is missing from each one.

A popular page with many No votes is usually your top priority. See Reader Feedback.

#

Auditing API docs: check them against the code

For an API collection, the most valuable audit compares the docs with your current code. Open your coding agent in the repo and ask:

Use the DocStar MCP. Read our API routes in this repo and compare them with the endpoints in our "Payments API" collection. List every endpoint that is missing, renamed, or has different fields than the docs say. Then update the endpoint docs to match the code, as drafts.

This matters because in DocStar the same API docs feed your docs site, llms.txt, the CLI and the MCP server that AI agents use to call your API. If a field name in the docs is wrong, an agent calling your API sends the wrong field and the call fails.

If your API collection already has an MCP server, its Logs help here too. In the collection's MCP tab you can see every call AI assistants made through your MCP server: what the assistant sent, the request, and your API's response. A 404 usually means a wrong path or id, and a 400 or 422 a wrong request body, which often points to a docs gap. Calls are kept for two weeks, and you need edit access to the collection to see them. For a deeper version of this check, see How to Test If AI Agents Can Use Your API Docs.

#

Keep it current: make the audit a habit

One audit fixes today's docs. Keeping them right is a habit, and DocStar makes it a small one.

  • Run the audit after every release. Same prompt, scoped to what changed: "Read the release notes for v2.4 and update any DocStar pages they affect, as drafts."

  • Keep API docs next to the code. With GitHub Sync, your OpenAPI files live in the repo and change in the same pull request as the code. A line in AGENTS.md tells your coding agent to update the endpoint's spec in the same change, and on push DocStar updates the docs site, MCP tools and CLI commands. Spec changes show up in the PR diff, so they get reviewed like code. Your agent can set it up in one prompt: "Set up DocStar GitHub Sync for this repo."

  • Know the limit. GitHub Sync works when the agent (or a person) updates the spec with the change. If someone changes code and skips the docs, the docs drift and nothing catches it automatically. That is exactly why a regular audit prompt is worth keeping.

Read more about this workflow in What Is Docs-as-Code?

#

Prefer to audit by hand?

You can still do it yourself in DocStar. Use the sidebar filter to show only Published or Unpublished pages, open Analytics to sort pages by reads and feedback, check each page's SEO score, and open Logs in the sidebar to see who changed what across the collection. It works, but it is the slow version of the same audit.

#

Why teams choose DocStar for AI-driven docs work

  • One workspace for everything. API docs, help docs, FAQs, changelog and blog live together, so one agent can audit all of them.

  • Agent-first by default. The DocStar MCP lets Claude, ChatGPT, Cursor, Codex and others read, write, organise and publish your docs with browser sign-in.

  • Safe changes. The agent asks before it changes anything, edits are saved as drafts, old URLs redirect automatically and every page has a version history.

  • Docs that serve people and AI. Every collection gets llms.txt, a Markdown copy of every page and its own MCP server; API collections also get a CLI.

  • Real reader signals. Reads, SEO scores and "Was this helpful?" feedback show where to start.

#

FAQ

Can an AI agent change my live docs without asking? No. With the DocStar MCP, the assistant shows you what it will create, change or publish and waits for your OK. Every edit is saved as a draft, and drafts never reach your live docs or your MCP server until you publish.

Which AI assistants can audit my DocStar docs? Any assistant that supports MCP, including Claude, Claude Code, ChatGPT, Cursor, VS Code and Codex. Connect it from the connector directory or add https://mcp.docstar.io/mcp as a custom MCP server.

Do I need an API key? No. You sign in to DocStar in your browser the first time the assistant needs your workspace. If your assistant can't connect that way, you can use an Auth Key instead.

What if the agent's fix is wrong? Don't publish the draft, or restore an earlier copy from Version History or Published History. Restoring a published version loads it as your current draft, so you review it before it goes live again.

How often should we audit our docs? Run a full audit once, then a short one after each release. With GitHub Sync for API docs and a release-time audit prompt, most problems are caught before readers find them.

#

Get started free

Connect your AI assistant to DocStar and run your first docs audit today. Get started free.

audit docs with AIdocumentation auditAI agentDocStar MCPdocs maintenance