Writing Tool Descriptions the Model Actually Understands

When an agent has access to more than a few tools, the model doesn't read your code — it reads text, and the text it reads at decision time is the `description` field on each tool. Every call, the model receives the full list of tool schemas (`name`, `description`, `input_schema`) and has to pick, in a single forward pass, which one — if any — matches what the user is asking for. Lesson 02 covered the anatomy of a tool definition: this lesson is about the one field inside that anatomy that actually steers selection.

A description that reads well to a human engineer can still fail the model, and a description that looks terse or slightly awkward on the page can outperform it, because the two audiences optimize for different things. A reviewer wants clarity and completeness. The model wants to differentiate, in a fraction of a forward pass, this tool from the nine others sitting next to it in the same request. That difference is the whole subject of this lesson.

The practical consequence is that description quality is never absolute — it's relative to the toolset it ships inside. A description like "Fetches an order" is fine alone with no other tools, but wrong the moment a `search_orders` or `list_recent_orders` sits beside it, because now the model has three plausible matches for "check on my order" and only one field distinguishing them. This lesson treats the description as a selection prompt: something written to be discriminated, not just understood.

Analogy🏏Cricket

🏏 Think of it like cricket: Rohit Sharma doesn't read a bowler's full biography before he throws them the ball in the 19th over — he has a split-second mental card for each bowler in his attack, built from what makes each one different from the others standing at fine leg. Bumrah's card says 'yorker specialist, death overs, use when the batter is set and needs containing.' Shami's card says 'new-ball swing, use in the powerplay, not the death because his yorker is inconsistent under pressure.' Both bowl fast and both take wickets, so if their cards said the same thing — 'good fast bowler, takes wickets' — Rohit would be guessing every change he made, and guessing wrong under lights at a packed Eden Gardens. What makes the captaincy work is that each card exists relative to the other cards in the same XI: Bumrah's note only matters because Shami, Bhuvneshwar and Hardik are also on the field, each needing to be told apart in one line. A scouting note written for a solo trial, with no other bowlers to compare against, would never survive a real over-by-over call with five options on the board. The insight: a tool description, like a bowler's mental scouting card, isn't there to document the bowler in full — it's there to let the one making the call, in real time, tell this option apart from every other option in the same attack.