July 30, 2026 · 6 min read
AI agents don't have real-time awareness. They reason from what they've been given — their training data and the context retrieved from tools like MCP servers. When that retrieved context is stale, the agent doesn't know it. It answers confidently from outdated information, producing hallucinations that aren't random errors — they're accurate descriptions of a product that used to exist.
Freshness failure is easy to identify in retrospect and hard to catch in real time. A few common patterns:
Feature amnesia. A product ships a new feature. The docs are updated. But the MCP server's index was last refreshed six weeks ago. An agent querying the index says "this feature doesn't exist" or describes the old behavior. The user assumes the agent is wrong about the feature; the product assumes the agent is working correctly. Both are partially right.
Deprecated API persistence. An API endpoint is removed in a new release. The docs are updated with a migration guide. The index still has the old endpoint. An agent recommends the deprecated endpoint. The user follows the advice, hits a 404, and concludes the agent is unreliable.
Pricing drift. A SaaS product changes its pricing. The index still has the old tiers. An agent quotes the old price in a sales context. The customer is surprised at checkout. Trust is damaged — not just in the agent, but in the product.
These failures share a structure: the agent is doing its job correctly. It's retrieving the most relevant content from the index and synthesizing an accurate answer — accurate as of the last index refresh. The failure is in the index's currency, not the agent's reasoning.
RAG (Retrieval-Augmented Generation) retrieves relevant chunks from an index and provides them as context for the agent's response. It solves the context window problem — you can't fit your entire documentation into an LLM's context, but you can retrieve the relevant parts. It doesn't solve the freshness problem — the retrieved chunks are only as current as the last time the index was built.
Most RAG implementations treat indexing as a one-time or batch operation: crawl once, embed, store. Re-indexing is expensive (crawling, embedding, and storing all pages) and is done infrequently — weekly, monthly, or never after initial setup.
The result is a freshness gap: the index is always some amount of time behind the live documentation. For fast-moving products, this gap can mean the agent is working from fundamentally outdated information within days of an index build.
Freshness is not binary — it's a distribution across pages. Some pages change daily (changelog, blog, pricing). Some change monthly (feature docs). Some almost never change (foundational concepts, architecture docs). A useful freshness metric looks at the age distribution of indexed content weighted by how frequently those page types change.
The pages that matter most for agent accuracy are also the ones most likely to drift:
The most effective strategy is triggering re-indexing on documentation changes rather than on a schedule. When a docs update is deployed, fire a webhook that tells the indexer to re-crawl the changed pages.
This is what AgentReady's refresh_site MCP tool enables: an agent or automated system can trigger a re-index at deployment time. The MkDocs plugin (mkdocs-agentready) does this automatically on every mkdocs build — the index is always in sync with the built docs.
For teams using CI/CD, adding a webhook call to the deployment pipeline keeps the index current without any manual intervention:
# In your deployment pipeline
- name: Refresh AgentReady index
run: |
curl -X POST https://www.agentready.it.com/api/submit \
-H "Content-Type: application/json" \
-d '{"domain": "docs.yourproduct.com", "refresh": true}'Not every page needs the same refresh frequency. A tiered strategy re-indexes high-drift pages frequently and low-drift pages less often:
This reduces the total indexing cost while keeping the highest-impact pages current.
Include index age in tool responses so agents can surface it to users. An agent that says "based on documentation indexed 2 hours ago" is more trustworthy than one that states outdated information as current fact. It also gives users a way to request a refresh when they suspect the index is stale.
// In your ask_site response
{
"answer": "...",
"citations": [...],
"indexedAt": "2026-07-30T08:00:00Z", // when this content was indexed
"freshnessWarning": null // or "Content older than 7 days"
}Give agents the ability to request a re-index when they detect a potential freshness issue. Signals that a refresh might be warranted: the user asks about a feature the agent can't find, the user says the answer seems wrong, or the agent's confidence score is low on a question about a recent release.
This is one of the use cases for AgentReady's refresh_site tool — an agent that suspects its knowledge is stale can request a refresh and then re-query with current content, within the same conversation.
Enterprise customers evaluating AI agent tools increasingly ask: "What's your freshness SLA?" — how long between a documentation change and that change being reflected in agent answers?
This is a reasonable question that most RAG tools don't have a good answer for, because they treat indexing as an infrastructure detail rather than a product promise. The right answer depends on your architecture, but a reasonable target for a webhook-triggered system is: changes reflected within 5 minutes of deployment. For scheduled re-indexing, the SLA is the schedule interval.
Teams that can answer this question precisely — "our index is always within 10 minutes of a docs deploy" — have a meaningful advantage in enterprise sales over teams that say "we re-index periodically."
AgentReady supports webhook-triggered re-indexing via the refresh_site MCP tool and the MkDocs/Starlight/Sphinx plugins. Index your site and keep it current automatically.