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:
Open Improve โ Content gaps and filter by severity, topic, or type.
Select a finding to review its problem, supporting evidence, and recommendation.
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.
Step 3: Find and investigate broken links
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
Open Improve โ Broken links to review unresolved findings.
Select a finding to inspect the affected URL and suggested destination.
Check whether the suggested redirect points to the right content.
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:
Open Improve โ Style guide โ Checks.
Select Run a check and choose the section to inspect.
Review the issues GitBook Agent identifies and the proposed changes in the resulting change request.
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:
Review what the agent added, removed, or changed.
Verify factual accuracy, particularly for API behavior, code examples, and configuration instructions.
Check that the update follows your style guide.
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
Share
Read more
Tutorials & tips
Get the GitBook newsletter
Get the latest product news, useful resources and more in your inbox. 130k+ people read it every month.
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?
Create & Publish
Solutions
Resources
ยฉ 2026 Copyright GitBook INC.
440 N Barranca Ave #7171, Covina, CA 91723, USA. EIN: 320502699
Get an AI summary

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

Create & Publish
Solutions
Resources
ยฉ 2026 Copyright GitBook INC.
440 N Barranca Ave #7171, Covina, CA 91723, USA. EIN: 320502699
Get an AI summary
The State of Docs Report 2026
State of Docs brings together insights from documentation experts from across the industry

Create & Publish
Solutions
Resources
ยฉ 2026 Copyright GitBook INC.
440 N Barranca Ave #7171, Covina, CA 91723, USA. EIN: 320502699
Get an AI summary
The State of Docs Report 2026
State of Docs brings together insights from documentation experts from across the industry







