How to Keep AI Agent Knowledge Fresh: Stale Docs and the refresh_site Tool

Your documentation was indexed on a Tuesday. On Wednesday you shipped a breaking change. On Thursday an AI agent told a developer the old API still works. They wasted two hours debugging before they realized the agent was wrong — not because it hallucinated, but because it was answering from cached knowledge that was already out of date.

This is the stale index problem, and it's one of the most underappreciated failure modes in AI-powered documentation tooling. It doesn't look like a bug. It looks like a correct, confident, well-sourced answer — that happens to be wrong about your current product.

Why documentation indexes go stale

When a RAG system indexes your documentation, it creates vector embeddings of your content at a specific point in time. Those embeddings are stored in a database. When an agent queries your docs, it searches those stored embeddings — not your live site.

This is exactly what makes RAG fast and reliable for most queries. But it also means every change you make to your documentation — a new endpoint, a changed parameter, a removed feature — is invisible to the agent until the index is updated.

Indexes can go stale in several ways:

• A product update changes how an API works
• A pricing change makes old plan details wrong
• A new SDK version deprecates old methods
• A migration guide gets added that the agent doesn't know about

In each case the agent gives a confident answer from the indexed content — and the indexed content is wrong.

Freshness signals: letting agents know how old the answer is

The first tool against staleness is transparency. If every agent response includes a "last indexed" timestamp, developers can immediately see whether the answer comes from a recent crawl or a three-week-old snapshot.

AgentReady now includes a freshness signal on every ask_site response. When an agent queries a site, the response includes the crawl date of the most recently indexed source page used to generate the answer:

The free plan includes 5 team members, 10GB storage, and unlimited projects.

*Last indexed: Fri, 03 Jul 2026 17:15:55 GMT*

**Sources:**
- [Pricing — Example Docs](https://docs.example.com/pricing)

This one line changes the agent's behavior. A well-configured agent — or an agent pipeline that checks freshness — can now decide whether to trust the answer or trigger a re-index before responding to the user.

It also gives developers debugging information. If an agent gives a wrong answer about your API, the first question is: when was this indexed? Freshness signals make that question answerable without touching the database.

The refresh_site MCP tool

Knowing an index is stale is only half the solution. The other half is being able to fix it — ideally from inside the same agent conversation that surfaced the staleness.

AgentReady's new refresh_site tool lets agents trigger a full re-crawl of any indexed site without leaving the MCP conversation:

// Tool call
{
  "name": "refresh_site",
  "arguments": { "domain": "docs.example.com" }
}

// Response after ~30s
"Successfully re-indexed docs.example.com in 28.4s.
ask_site will now return fresh content."

The tool wipes the existing index for the domain, re-crawls from the site root, re-embeds all content, and regenerates the site's AI-readable summary. When it completes, the next ask_site query returns answers grounded in the current content.

When to use refresh_site

The tool is designed for a few specific situations:

After a significant docs update. If you've shipped a new version of your API, a new pricing structure, or a major feature — refresh the index before agents answer questions about it. A site that was indexed last week doesn't know about changes you shipped this week.

When an agent returns a wrong answer. If you know your docs cover a topic but the agent says they don't, or gives outdated information, the first thing to try is a refresh. The existing index may simply predate the relevant content.

As part of a CI/CD pipeline. If your documentation is auto-generated from code — OpenAPI specs, JSDoc comments, README files — you can trigger a refresh_site call as part of your deploy process. Every doc deploy keeps the agent index in sync.

The CI/CD integration pattern

The most reliable way to keep an agent index fresh is to tie it to your documentation deploy. Here's a minimal pattern using GitHub Actions:

# .github/workflows/refresh-docs-index.yml
name: Refresh AgentReady index after docs deploy

on:
  deployment_status:
    # Only run when the docs site deploy completes successfully

jobs:
  refresh:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - name: Refresh AgentReady index
        run: |
          curl -s -X POST https://www.agentready.it.com/api/mcp \
            -H "Content-Type: application/json" \
            -d '{
              "jsonrpc": "2.0",
              "id": 1,
              "method": "tools/call",
              "params": {
                "name": "refresh_site",
                "arguments": { "domain": "docs.yoursite.com" }
              }
            }'

This runs automatically whenever your docs deploy succeeds and takes under 60 seconds. Your agent index stays in sync with your live documentation without any manual intervention.

What happens during a refresh

Under the hood, refresh_site does the following:

1. Clears the existing page and chunk records for the domain (FK cascade wipes embeddings)
2. Crawls from the domain root — not the original submitted URL — so a site submitted via a deep path gets fully re-indexed
3. Re-embeds all content using text-embedding-3-small
4. Regenerates the site's AI-readable summary and llms.txt
5. Updates the site record to status: ready with the new page_count and metadata

If the crawl fails for any reason — the site is unreachable, returns empty content, or the embedding step errors — the tool returns a clear error message noting that the previous index was cleared. In that case, re-submitting via submit_site will start fresh once the site is accessible again.

Freshness as a first-class concern

The best AI-powered documentation tooling doesn't just answer questions accurately — it answers them accurately about the current state of your product. That requires treating freshness as a first-class concern, not an afterthought.

Freshness signals let agents surface their own staleness. The refresh_site tool lets them fix it. Tying both to your CI/CD pipeline means you can ship documentation changes and trust that agents will be answering from the latest content within minutes.