When an AI doc agent produces a vague draft, the reflex is to give it more. More pages, the whole spec, every related guide, the full changelog. If it had been confused before, surely the problem was that it didn't have enough to go on.
Usually it's the opposite. The draft was vague because the agent had too much, not too little, and it couldn't tell which parts mattered.
Context isn't free attention
A model reads everything you hand it, but it doesn't read everything equally well. The more material in the context, the more thinly the model's attention spreads across it. Bury the one relevant paragraph in forty pages of loosely related docs and the agent has to find it before it can use it. Sometimes it does. Often it averages across everything and gives you a draft that's technically informed by all of it and committed to none of it.
You've seen the result. The draft is plausible, hedged, and generic. It reads like it's describing your product from a distance. That's the signature of an agent that had too much input and no signal about what to weight.
More context, more contradictions
There's a second problem that scales with volume. The more you include, the more likely the context contains things that disagree with each other.
Your docs are not perfectly consistent. An old guide describes the v1 behavior. A newer page describes v2. A migration note sits between them. To a human reading in sequence, the timeline is obvious. To an agent handed all three at once with no ordering, they're three equally weighted claims that happen to contradict. It picks one, or worse, it blends them into a description of a version that never existed.
This is one of the quieter agent failure patterns: the hallucination isn't invented from nothing. It's assembled from real but conflicting sources you handed over together.
Curated beats comprehensive
The fix isn't a bigger context window. It's a smaller, sharper one. The pages most relevant to the change, the current version, the canonical example. An agent working from five pages that are all correct and all relevant produces sharper drafts than one working from fifty pages of mixed quality and mixed vintage.
This is why using your existing docs as context works as well as it does, but only when those docs are good. Point the agent at your strongest, most current pages and it has a clean target. Point it at everything and you've reintroduced the noise you were trying to avoid.
A few principles that hold up:
- Recency over completeness. The current page beats the current page plus three deprecated ones.
- Relevant over related. "Touches the same endpoint" is worth more than "mentions the same product area."
- Resolved over raw. A page where you've already settled the v1-versus-v2 question beats three pages that leave the agent to settle it.
The exception worth naming
This isn't an argument for starving the agent. An agent with too little context guesses, and guessing is its own failure mode. There's a real floor: it needs enough to ground the specific change it's drafting.
The point is that the curve isn't monotonic. Going from too little to enough makes drafts better. Going from enough to everything makes them worse again. The job is finding the middle, and the middle is usually narrower than your instinct says. When a draft comes back vague, the first question shouldn't be "what else can I give it." It should be "what in here is competing with the part that matters."
Good prompting patterns help here too, by telling the agent which of the context to lean on rather than leaving it to weigh everything evenly.
How ReadMe puts this together
ReadMe's AI agent is grounded in your docs, and the leverage is in keeping those docs clean. A docs audit that clears out stale and contradictory pages doesn't just help your readers. It sharpens every draft the agent produces, because there's less wrong material competing for its attention. Curated docs in, sharper drafts out.
So the next time a draft disappoints, resist the urge to pile on context. Trim it instead. Start a project to ground an agent in your best pages, or talk to us about Enterprise.
