Tutorials & tips

Published:

18 Nov, 2026

How to audit and improve your docs with GitBook Agent and MCP

AI summary

GitBookโ€™s Content gaps, Broken links, and Style guide features help teams identify documentation quality problems. Using GitBook Agent and MCP, teams can investigate findings, prioritize issues, and prepare fixes in change requests for human review. Breaking the audit into individual steps gives teams greater control over the process, while recurring audits make it easier to maintain documentation quality as products evolve.

Product releases and API updates can leave your documentation outdated, inconsistent, or incorrect. Those errors affect readers and the AI assistants and coding agents that use your docs to answer questions and complete tasks.

For teams managing hundreds of pages, itโ€™s hard to manually review everything. Thatโ€™s why we built GitBookโ€™s Content gaps, Broken links, and Style guide features โ€” to help you identify quality issues, while GitBook Agent and MCP let you investigate findings and prepare fixes.

This guide walks through a documentation audit one step at a time, with prompts to help you choose what to investigate and when to prepare changes.

Before you start: Set up your audit

You can audit your documentation directly in GitBook or using an AI agent connected with GitBook MCP. Both approaches work with your existing documentation and quality tools.

First, open your GitBook site and find the Improve section. Weโ€™ll be using three features:

  • Content gaps: Identifies missing, outdated, or incorrect information. You can configure relevant sources, such as support conversations or forums. GitBook AI Assistant conversations are automatically available as a source if the Assistant is enabled.

  • Broken links: Finds broken URLs pointing to your docs, as well as links in your documentation that lead to unavailable external websites.

  • Style guide: Defines your teamโ€™s terminology, tone, and formatting rules for GitBook Agent to follow.

If youโ€™re using an external AI agent, connect it to GitBook MCP. You can use supported clients such as Claude, ChatGPT, Cursor, or Codex using official plugins.

Alternatively, connect manually using our endpoint at https://mcp.gitbook.com/mcp.

Make sure youโ€™re connecting to GitBook MCP rather than the read-only MCP server for published documentation.

Note: Some quality features require an Ultimate or Enterprise site, and certain operations require editing or admin permissions.

Step 1: Start with a documentation quality overview

Start by asking your MCP-connected agent to summarize the existing quality findings available for your site to test its visibility. We suggest you keep this first pass read-only:

Review the available documentation quality findings for [SITE NAME OR URL] using GitBook MCP.

Give me an overview of unresolved issues, grouped by category and priority. Highlight the most serious findings and tell me which checks you couldnโ€™t access.

Donโ€™t investigate individual findings in detail or make any changes yet.

Use the overview to choose which findings to investigate first. Depending on which quality checks your MCP client can access, you may also want to review findings in GitBookโ€™s Improve section.

Step 2: Find missing and outdated information with Content gaps

Customers may repeatedly ask about an API authentication error your docs donโ€™t explain. Or a feature may have changed while the instructions still describe its old behavior.

GitBook Content gaps identifies problems like these by comparing your published documentation with questions and evidence from connected sources, so you can fix them before they trip up more users.

Using an AI agent

Through GitBook MCP, your agent can retrieve Content gaps, inspect their supporting evidence, and investigate the relevant documentation.

For example, you could ask:

Find the five highest-severity unresolved Content gaps related to API authentication.

Review the supporting evidence and existing documentation, then recommend which issues we should address first and why.

Donโ€™t make any changes yet.

Use the evidence and recommendations to select a finding to work on.

Using the GitBook UI

To investigate a finding in GitBook:

  1. Open Improve โ†’ Content gaps and filter by severity, topic, or type.

  2. Select a finding to review its problem, supporting evidence, and recommendation.

  3. Inspect the original sources and relevant documentation to confirm the issue.

Itโ€™s important to remember that not every finding needs a fix. Sometimes the information already exists, the evidence isnโ€™t sufficient, or the recommendation just goes too far to solve a minor issue. You can reject findings that donโ€™t require action.

Keep the findings you want to address for Step 5, where youโ€™ll prepare fixes.

When documentation moves or changes, old URLs can remain in search results, bookmarks, and links from other websites. But links within your documentation can break, too โ€” perhaps youโ€™ve linked to a third-party API reference thatโ€™s moved or a resource thatโ€™s no longer available.

GitBook Broken links identifies both problems, helping you find dead ends and decide how to resolve them.

Using an AI agent

Imagine youโ€™ve moved your API authentication guide from /api/auth to /guides/authentication.

You could ask your agent:

Investigate broken links in my API documentation, including incoming URLs and links to external websites.

Identify likely causes and recommend appropriate fixes โ€” redirects for moved documentation pages, or updated links where external resources have changed.

Prioritize the most important issues and donโ€™t make any changes yet.

Where supported, your agent can investigate GitBookโ€™s findings through MCP. Alternatively, you can provide specific broken URLs for it to investigate against your siteโ€™s documentation.

Using the GitBook UI

  1. Open Improve โ†’ Broken links to review unresolved findings.

  2. Select a finding to inspect the affected URL and suggested destination.

  3. Check whether the suggested redirect points to the right content.

  4. Create an appropriate redirect, or save it as a draft for later review.

You can also use the Analyze tab to investigate URLs without suggested redirects.

For incoming broken URLs, you can create redirects to help readers reach the right page. For broken external links, youโ€™ll need to update or remove the link in the page containing it. But check that the destination is genuinely unavailable before making changes, since some failures can be temporary.

Step 4: Check consistency with Style guide

Inconsistent terminology, formatting, and structure can make your docs harder to follow. For example, one page might refer to โ€œAPI tokensโ€ while another calls the same feature โ€œaccess keys.โ€

GitBookโ€™s Style guide lets you define writing standards that GitBook Agent can apply when editing and reviewing content.

Using an AI agent

You can ask an MCP-connected agent to inspect selected documentation pages against your existing style guide.

For example:

Review the API authentication documentation against our GitBook style guide.

Identify inconsistent terminology, formatting, heading structure, or tone. List the relevant pages and explain which rules they donโ€™t follow.

Donโ€™t edit anything yet.

This keeps the review focused on a specific area. The agentโ€™s ability to retrieve and apply your style guide depends on its available tools and context.

Using the GitBook UI

For a broader audit of existing content, use the dedicated Style guide Checks:

  1. Open Improve โ†’ Style guide โ†’ Checks.

  2. Select Run a check and choose the section to inspect.

  3. Review the issues GitBook Agent identifies and the proposed changes in the resulting change request.

  4. Adjust or approve the changes before merging.

These checks are particularly useful after major documentation updates or changes to your product terminology, as the style guide will flag anything you missed on your first pass.

Step 5: Prepare and review your improvements

Choose a few high-priority findings from your audit to address first. For example, you might choose a missing troubleshooting section thatโ€™s generating support questions, or outdated instructions for a commonly used API.

Ask your agent to prepare a fix

Once youโ€™ve investigated a finding and decided how to resolve it, you can ask your agent to create a change request.

For example:

Create a GitBook change request to address the API authentication content gap weโ€™ve just reviewed.

Use the supporting evidence and our existing documentation to draft the improvement. Follow our style guide and preserve the surrounding page structure.

Leave the change request ready for my review. Donโ€™t publish anything.

You can also generate changes directly from Content gaps in the GitBook app by selecting Create change request(s) on an individual finding.

For broken URLs, apply or review the appropriate redirect through GitBookโ€™s Broken links interface. Style guide Checks already generate change requests containing suggested corrections.

Review before publishing

GitBook uses change requests to keep proposed content edits separate from published documentation.

For each change request:

  1. Review what the agent added, removed, or changed.

  2. Verify factual accuracy, particularly for API behavior, code examples, and configuration instructions.

  3. Check that the update follows your style guide.

  4. Request adjustments or merge the change when youโ€™re satisfied.

You can also review change requests with GitBook Agent before publishing.

An agent can identify a real problem and still propose an inaccurate fix. Your team needs to verify the changes and decide whatโ€™s ready to publish.

Step 6: Make your documentation audit a recurring workflow

GitBook monitors Content gaps and Broken links in the background as your product and documentation change. Set aside time to regularly review new findings, prioritize problems, and prepare improvements.

Start with a weekly audit

Once youโ€™ve completed your first audit, you can combine the individual steps into a single prompt that checks for new issues and prioritizes what needs attention.

Run it weekly through your MCP-connected AI client to keep track of your documentation quality without repeating the entire process manually:

Review the new and unresolved documentation quality findings from the last seven days, alongside any outstanding high-severity issues.

Give me a prioritized summary of what needs attention, including the supporting evidence and recommended next steps.

Donโ€™t make changes yet. I want to choose which findings to investigate and fix.

You could run this every Monday, investigate the highest-priority findings, and review proposed fixes during your teamโ€™s regular documentation maintenance time.

Automate the process further

If your automation platform or agent runner supports scheduling and MCP, you can schedule a weekly task to retrieve available quality findings and produce a prioritized report for your team.

The exact setup depends on your automation platform and the GitBook MCP operations it supports. You can complete any checks unavailable through MCP as part of your regular UI review.

Once youโ€™ve reviewed the findings, you can direct your agent to investigate and prepare the fixes that matter most. Automating the report reduces the time your team spends gathering findings while keeping decisions about fixes and publishing with your reviewers.

Keep your documentation improving

Start with one section of your documentation, run the overview prompt above, and investigate the findings that matter most to your readers. Use what you learn to set the scope and frequency of future audits.

Get started with GitBook MCP and try the audit prompts with your own docs.

โ†’ How we rebuilt GitBookโ€™s docs with Claude and GitBook MCP

โ†’ By the numbers: Where documentation quality breaks down in 2026

โ†’ How to create and publish documentation with AI and MCP

Share
Get the GitBook newsletter

Get the latest product news, useful resources and more in your inbox. 130k+ people read it every month.

Email

Accurate docs. Better answers.

Your docs are already feeding AI. Are users getting the right answers or the wrong ones?

Accurate docs. Better answers.

Your docs are already feeding AI. Are users getting the right answers or the wrong ones?

Accurate docs. Better answers.

Your docs are already feeding AI. Are users getting the right answers or the wrong ones?

Enterprise

Intelligent documentation thatโ€™s built to scale




Verifone thumbnail
Verifone logo - white
Verifone

How Verifone increased assistant traffic by 8x after migrating to GitBook

The State of Docs Report 2026

State of Docs brings together insights from documentation experts from across the industry

Verifone thumbnail
Verifone logo - white
Verifone

How Verifone increased assistant traffic by 8x after migrating to GitBook

The State of Docs Report 2026

State of Docs brings together insights from documentation experts from across the industry

Verifone thumbnail
Verifone logo - white
Verifone

How Verifone increased assistant traffic by 8x after migrating to GitBook

The State of Docs Report 2026

State of Docs brings together insights from documentation experts from across the industry