A recent study of coding-agent trajectories found that 60.5% of observed documentation interaction targeted artifacts created for agents, such as instruction files and working notes. API reference documentation accounted for just 1.3%, while troubleshooting documentation accounted for 0.4%. My first reaction was: of course. Agents are explicitly taught to discover their instructions, and working notes are part of how they operate. The more interesting question is whether they read the right documentation before they make a decision that depends on it.
Agents already know how to build things
Modern models have been trained on enormous amounts of code and technical writing. Ask an agent to build an application with a popular SDK and it often knows enough to get started. It knows the SDK exists and roughly how it works. It has seen common authentication patterns and code that looks like what you need. That’s an incredible advantage.
Requiring an agent to rediscover everything from documentation on every task would waste time and context. An agent can consult no API reference and still produce a current, correct implementation. The risk is that agents don’t always know when to stop trusting what they know.
Model knowledge has an expiration date
Software changes continuously. SDKs release new versions and recommended implementation patterns change. Sometimes an API is deprecated. Sometimes an entire SDK is replaced.
Model knowledge doesn’t evolve at the same pace. A newer model doesn’t necessarily have newer knowledge either. In our Agent Experience research, we’ve seen newer models perform worse with recent technologies than the models they replaced. A model’s release date tells us little about the recency of its knowledge.
Not everything expires equally quickly though. HTTP doesn’t become obsolete every six weeks, and the fundamentals of OAuth aren’t reinvented every quarter. Verifying every fact would discard much of the value that model knowledge gives us. So how do we use that knowledge without letting an outdated assumption determine the solution? We change what the agent does with its first answer.
Start with a hypothesis
When a user describes what they want, let the agent infer their intent and form an initial understanding of the solution. That understanding is useful because it points the agent towards what it needs to investigate. But it shouldn’t become a plan yet. It should remain a hypothesis: strong opinions, loosely held.
The agent might think that the task probably requires SDK A with a particular authentication flow. Now it has something concrete to test. Before committing, it checks the assumptions most likely to have aged against current authoritative guidance.
The trajectory becomes:
- Infer intent.
- Form a working hypothesis.
- Validate assumptions that may be outdated.
- Form a plan.
- Execute.
The distinction between steps two and four matters. A hypothesis helps the agent decide what to verify. A plan commits it to choices that become increasingly expensive to change.
Documentation should shape the plan
We’ve seen in Agent Experience research that agents tend to form plans early. Once they do, new information has to compete with an existing trajectory. Imagine that an agent decides to use SDK A and starts implementing. When something fails, it checks the documentation and discovers that SDK B replaced A for new applications. The agent now needs to undo work and revisit decisions built on its original choice. It also needs to overcome its own confidence that the original approach was reasonable.
Now consider the same discovery while the agent’s understanding is still provisional. It thinks SDK A is appropriate, checks current guidance and learns that SDK B supersedes it. The hypothesis changes before anything depends on it. Nothing needs to be undone because there was nothing to undo yet. Documentation shaped the plan instead of correcting it.
Verify what can expire
This doesn’t mean that every task should begin with an hour of reading. The agent should verify decisions whose inputs are sensitive to change. The choice of SDK is one example. The current authentication approach might be another. Language fundamentals usually don’t need the same treatment. Neither do stable protocols, unless the task depends on a recent extension or a vendor-specific implementation.
The point isn’t to create a universal list. It’s to teach agents to recognize when a decision relies on knowledge with a short shelf life. Their existing knowledge can identify the likely solution and, just as importantly, which parts of that solution might have expired.
This also changes what good skills and instructions look like. They don’t need to reproduce an entire API reference. Instead, they can require the agent to check current official guidance before making decisions in areas known to change quickly. That uses less context while giving current information a chance to influence the work. Timing is what makes the instruction useful. Verification must happen while the agent’s understanding can still change cheaply.
Don’t optimize for more reading
The low proportion of API-reference interaction doesn’t mean agents should read more API documentation. Maybe 1.3% is exactly right. An agent that reads twelve pages and still chooses a deprecated SDK isn’t doing well. Another agent might consult one authoritative page and update its hypothesis before producing a current implementation. Counting reads would reward the wrong behavior.
Correct decisions are the goal. What matters is whether authoritative information enters the trajectory when a decision depends on knowledge that may no longer be current.
Measure decisions, not reads
This suggests a different way to evaluate agent experience. Instead of asking how much documentation an agent consulted, ask whether it verified assumptions that could be outdated before committing to them. Give an agent a task for which its model knowledge points towards an older SDK. Does it plan around that SDK immediately? Does it begin implementing and consult documentation only after the code fails? Or does it treat its first answer as provisional, check current guidance and then plan? We want calibrated documentation consumption, with authoritative information entering the trajectory when it matters.
Models knowing how to build software before reading a single page is a feature. We should use that knowledge to understand the problem and identify a likely solution. But software changes, so we shouldn’t confuse a likely solution with a committed plan.
Let the agent form a hypothesis. Verify the parts that may have aged, then decide what to do. Let current information shape the decision before the agent starts acting on it.