Spots 
Give an agent a link to a 300-page API reference and watch what happens. It doesn't read it end to end. It samples a few pages, guesses at the auth flow, writes some code, hits an error it didn't expect, and burns another five turns figuring out what the docs already told you on page 40.
The docs aren't the problem. Docs are written for a human skimming toward the one endpoint they need. An agent needs something else: a procedure it can execute without rediscovering the same three gotchas every single session.
Whenever I wire an agent up to a new API now, I stop it before it starts writing code and make it (or me) produce one file first. Not notes — a procedure, with four fixed parts:
1. When this fires. One sentence describing the task that should trigger this procedure, so the agent doesn't reach for it when a simpler tool would do.
2. The steps, in order. Auth first, then the actual call shape, then whatever cleanup or pagination the API demands. Written as instructions, not prose about the API's philosophy.
3. Named failure modes. Not "handle errors gracefully" — the specific ones. "This API returns 200 with an empty body when the resource doesn't exist, not a 404." "Rate limit resets on a rolling window, not a fixed clock." These are the things you only learn by hitting them, and writing them down once means nobody on your team hits them twice.
4. One snippet that actually runs. Not a curl example lifted from the docs — the real call, in your stack, that you've verified works today. That's the whole file. For most APIs it's 40-80 lines. Why the failure modes matter more than the happy path
The happy path is what the official docs already cover, usually well. The gap agents fall into is entirely in the failure modes — the API returning success-shaped garbage, the auth token that's valid but scoped wrong, the endpoint that's deprecated but still returns 200. None of that is in the reference docs, because reference docs describe intended behavior, not observed behavior.
Every hour you spend hitting one of these once and writing it down is an hour every future session with that API skips entirely. That's the actual leverage — not that the agent "knows the API," but that it never repeats a mistake you already paid for.
One procedure file for one API is a nice-to-have. It gets real once you're integrating five or six tools the same way, because the discipline is identical every time: same four sections, same bar for what counts as a documented failure mode. At that point you're not writing docs anymore, you're building a small internal library your agent actually consults instead of guessing from scratch each session.
Give an agent a link to a 300-page API reference and watch what happens.