Your Tool Descriptions Are Doing More Work Than You Think

Anthropic dropped a piece on writing tools for agents and it belongs in the same category as the posts that quietly reframe how you think about a problem — the ones where you finish reading and immediately go look at something you built with fresh disgust.

The premise sounds obvious until you sit with it: the tool description is the entire interface. Not a hint, not documentation — the interface. A human engineer using your API can grep the codebase, look at examples, ask a colleague, run the thing and see what breaks. The agent has the text you wrote. That's it. Whatever intuition you assumed the caller would have, the agent does not have it. Whatever context seemed too obvious to mention, the agent is missing it.

This means the thing most tool authors spend zero time on — the docstring, the parameter description, the names of things — is the thing that determines whether the tool gets used correctly at all.

The distinction that hit me hardest: there's a difference between explaining what a tool does and explaining when to use it. A function signature tells you the former. The latter is what agents actually need, because agents have to choose among tools before calling any of them. If you have a read_file and a get_document and the difference isn't immediately legible from the description, you will watch the agent oscillate between them for reasons that feel mysterious until you realize the mystery is that you never told it which one to pick.

Error messages are tool design. This one most people completely ignore. When an agent calls your tool wrong and gets back Error: invalid parameter, that error message is now a prompt. The agent is going to read it and decide what to do next. If the message says nothing useful, the agent invents a next step. If the message says "this endpoint requires an ISO 8601 timestamp, received Unix epoch integer," the agent has something to work with. The error is part of the interface and most people treat it like logging.

Idempotency isn't just a nice property — with agents it's load-bearing. Agents retry. They get confused and call things twice. They backtrack and replay steps. A tool that silently creates a duplicate record on the second call is going to generate bugs that look insane until you understand the agent's call history, at which point they look merely embarrassing.

None of this is exotic. It's the same thinking that separates a well-designed API from a nightmare one — except the stakes are different, because the "client" reading your interface can't ask for clarification and won't always tell you when something doesn't make sense. It'll just make something up and move on.

Go read it. Then go look at your tools.