A tool definition is the only thing the model ever sees of your tool. It never reads your implementation, never inspects your database schema, never sees the try/except block around your API call — it sees a name, a description, and an input_schema, and from that alone it decides whether to call the tool, which one to call, and what arguments to send. Get the definition wrong and no amount of correct implementation behind it saves you: the model was never going to call it, or was going to call it with the wrong arguments, because the interface it was reasoning against didn't say what the tool actually does.
That makes the tool definition a strange kind of object. It is documentation, in the sense that its entire job is to be read and understood correctly by a reasoning system. But unlike documentation a human reads once and remembers, a tool definition is retransmitted and reread on every single API call in the conversation, whether or not the tool ends up being used that turn. Claude Opus 5 pays for the tokens in every tool definition on every call, the same way it pays for every other token in the request — a verbose, imprecise definition is not a one-time authoring cost, it's a recurring tax for the life of the session.
This lesson treats the tool definition as having exactly that dual nature — interface documentation and permanent token cost at the same time — and walks through what follows from taking both halves seriously: how to write a description that actually steers selection, how naming and parameter design act as affordances rather than decoration, and how to think about the token bill a toolset accumulates before a single tool has run.