Agent-friendly content needs maintenance. As your product changes and pages accumulate, yesterday’s clear context can become today’s stale answer. A few checks can fit into the maintenance routine you already have.
Watch what agents tell you
Your question set catches regressions you can predict. Mintlify’s analytics show you the ones you can’t:- Assistant analytics group the questions readers ask your site’s assistant into topics, with ratings for each answer. Topics with poor ratings point to missing, unclear, or outdated pages.
- Agent feedback comes from AI agents connected to your MCP server. When an agent finds a page that’s wrong or confusing, it can report the problem, and you’ll see it in your feedback analytics next to reader feedback.
- Traffic analytics show how many page views come from AI agents rather than people, so you can see which pages agents rely on most.
When the product changes
Documentation stops being agent-friendly the same way it stops being accurate: it was right once and then wasn’t updated. Agents don’t know when content is stale, so they present it with the same confidence as current information. When a product changes or you release a new feature:- Update the relevant pages before or alongside the release, not after
- Check whether terminology has changed. If a feature was renamed, find every page that uses the old name and update it
- Update your agent instruction files if a term changed
- Mark pages for removed features
hidden: trueor delete them, so they drop out ofllms.txtand AI context
Audit for terminology drift
Terminology consistency is hard to maintain as a team grows and different people contribute to content. Run a periodic audit:- List the canonical terms for your most important concepts in a shared style guide
- Search your content for synonyms and variants
- Update any pages using non-canonical terms
Check new pages are self-contained
Self-containment is hard to keep up because missing context is hard to spot while you’re writing. You know the subject, so you may not notice that a page depends on information found elsewhere. Add these questions to your review checklist for new pages:- Does this page assume the reader has read any other page?
- Does it use terms that are only defined elsewhere?
- If a reader arrived here from an agent’s answer, would they have enough context to act?
Keep llms.txt accurate
Mintlify’s generated llms.txt updates itself whenever you publish, so you don’t need to maintain the file. You do need to maintain what it’s built from: page descriptions, navigation order, and which pages are hidden. When you review a section, check that its descriptions still match its pages.
If you wrote a custom llms.txt, it won’t update on its own. Review it whenever you add, move, or remove pages, or switch back to the generated file.
A maintenance rhythm
- With every product release: Update affected pages, check for terminology changes, and update agent instruction files if a term changed
- Monthly: Review assistant analytics and agent feedback for unanswered questions, wrong answers, or outdated information
- Quarterly: Audit for terminology drift, check page descriptions, and check that high-traffic pages are self-contained
- After major content or access changes: Re-run your evaluation set and verify that each audience can retrieve only the intended sources
Go deeper
- Why agent-friendliness matters—An overview of how agents access documentation and why the highest-impact fixes are often configuration changes, not rewrites.
- The Agent-Friendly Documentation Spec—A spec that defines 28 checks for evaluating the agent-friendliness of your documentation.
Continue learning
- Structure docs that scale—Content types, navigation design, and keeping documentation accurate as your product grows
- Git and GitHub for Mintlify—Version control, branching, and collaboration workflows for documentation
- How to use Mintlify components—How to use Mintlify’s components to structure and format documentation effectively