Designing APIs for AI Agents and Tool Use — API Design & Best Practices

A human developer reading confusing API documentation can pause, reread it three times, check a forum, and eventually guess right. An AI agent calling that same API mid-task has none of that patience: it reads a tool's schema and description once, forms a plan, and calls it with whatever parameters seemed most plausible given the text it was shown. If the schema is ambiguous about whether `end_date` is inclusive, or the tool's description doesn't say what happens when a required resource doesn't exist, the agent doesn't shrug and go look it up — it guesses, commits to that guess by calling the tool, and may take several more actions downstream before anything reveals the guess was wrong. Designing for a human reader and designing for an agent caller are not the same discipline, and treating a tool schema like documentation for a person is where most agent-facing APIs quietly fail.

The shift that matters most is that the schema itself is now load-bearing, not supplementary. A human-facing API can lean on prose documentation, a getting-started guide, a support channel — an agent typically only sees what's in the tool definition and whatever error text comes back from a failed call. Every ambiguity you'd normally resolve with a paragraph of prose a developer might skim has to be resolved structurally instead: tight parameter types, explicit enums instead of free-text strings where the values are actually closed, and descriptions that state the non-obvious constraint directly rather than assuming context the agent doesn't have and can't ask about mid-call.

None of this is a new category of API design — it's the same discipline this course has covered throughout, applied to a caller with a specific and unforgiving failure mode. An agent that gets a vague, free-text error message can't parse it into a decision the way a human reading a stack trace can; it needs an error shape it can act on. An agent retrying a failed call after a timeout needs the same idempotency guarantee any unreliable-network caller needs, except an agent retries far more often and far less cautiously than most human-written client code does. This lesson is about what changes when the caller reading your contract is a model instead of a person, and what stays exactly the same.

Analogy🏏Cricket

🏏 Think of it like cricket: A seasoned umpire reading an unusual playing-condition clause mid-match can draw on years of accumulated context — precedent from similar situations, a quiet word with the match referee, general cricketing sense about what the clause is probably trying to prevent — to make a reasonable call even when the wording is a little loose. A brand-new trainee umpire sitting the same exam, working only from the exact text of the playing conditions in front of them with none of that accumulated context to fall back on, has to apply the clause exactly as written, and a loosely worded clause sends them toward whatever reading the literal text most directly supports, even if that's not what the rule-makers actually intended. Rule-makers who write playing conditions knowing trainees and inexperienced officials will also have to apply them write far more precisely than rule-makers who only imagine a seasoned umpire reading the document — every boundary case gets spelled out, because a trainee has no accumulated judgment to paper over an ambiguity, only the words on the page. Just as a trainee umpire applies a rule exactly as written with no outside context to resolve ambiguity, an AI agent applies a tool's schema and description exactly as written, with no outside context to resolve ambiguity either. Just as a rule-maker writing for a mixed audience of seasoned and trainee umpires has to write for the trainee's literal reading, not the veteran's forgiving one, an API designer writing a tool schema has to write for the agent's literal reading, not the assumption that a knowledgeable human will fill in the gaps. The insight is that precision that used to be optional, because a sufficiently experienced reader would fill in the gap correctly anyway, becomes mandatory the moment your actual reader has no accumulated judgment to fall back on and will act on the literal text exactly as given.