Tool Descriptions Are Contracts for a Reader That Cannot Ask Questions

Twenty years of operational documentation: runbooks, playbooks, API references, wikis nobody opens until something breaks at 3 AM. What made me decent at it was having a picture of the reader. Tired engineer, skims the overview, tries the obvious thing, hits an error, comes back and reads the constraints properly this time. You write to speed that loop up — generous with context, light on edge cases, because the reader closes the gaps herself.

Every part of that picture is wrong when the reader is a model.

A tool description is the text you hang on a tool definition so a model knows what the thing is for: an OpenAI function, an Anthropic tool, an entry in a Model Context Protocol server. The model sees other things too, the schema and the system prompt and whatever instructions the host passes along. But the description is the surface you control at the tool level, and it's the one most authors underwrite. From it, the model decides whether to call your tool at all and how to populate every parameter. It won't try the endpoint first to see what comes back, or read your source, or ask what you meant by "resource identifier."

A human who hits a gap in your docs routes around it. A model that hits a gap fills it from training data, and your tool now does whatever the model assumed it does.

An issue filed against Claude Code has this in miniature. A tool shipped a 9,336-character description covering roughly sixty browser-automation functions; the client truncated it at 2,048 characters, silently. Down about forty-five functions, the model began calling Playwright-style methods — waitForLoadState, getSnapshot, getConsoleMessages — that didn't exist in the sandbox it was driving. It didn't stall when the description shrank. It reconstructed the missing surface from things it had seen elsewhere. A human would have gone hunting for the rest of the list; the model had no rest of the list to hunt for. Worth knowing what your own host does to a long description before it reaches the model.

Anthropic's engineering team has taken to calling tools "contracts between deterministic systems and non-deterministic agents." Contract is the right word. Documentation is for learning; a contract specifies what happens at the boundaries, and ambiguity in a contract isn't settled by good faith. It's settled by whoever acts first, and the model always acts first.

The specs haven't caught up to that. The MCP specification (revision 2026-07-28) makes description optional, calls it a hint, and offers nothing on structure or quality. Anthropic's own guidance says detailed descriptions are "by far the most important factor" in tool performance and asks for three or four sentences on purpose, when to use it, what each parameter does, and what the tool does not return. Authors land in the gap between those two and fill it with the thing they already know how to write, which is API documentation.

Wrong muscle memory. Good API docs orient you with a narrative overview, show typical usage through examples, and omit constraints any competent developer would infer. A model doesn't need orienting, it needs boundaries. Examples can degrade tool selection outright for some reasoning models, which OpenAI's function-calling guide says in as many words. And the constraints you skipped because they're obvious: there is no obvious available here. There's your description, the schema, and whatever the host assembled around it. What you omit, the model infers, and inference from training data is the operation that produces invention.

Experienced developers pick this up fine, once they stop treating it as a skill they already have.