Tool design — descriptions

Read these first

• Tool design — granularity and surface

What you will know

• Write a tool description that gets the tool selected correctly

  The description is what the model uses to choose; it is the most load-bearing string in the system.

• Measure the token cost of tool descriptions across a representative multi-turn workload

  Repeated context inflation affects both billing and available context, although prompt caching can change the marginal cost.

• Cut a description in half without losing selection accuracy

  Shorter wording can remove ambiguity and reduce context pressure, but compression may erase distinctions between overlapping tools.

• Use the description to encode when *not* to call the tool

  Negative criteria prevent speculative calls when the model lacks required inputs or a direct answer is sufficient.

• Diagnose a wrong tool selection as a description problem

  Confusable names, overlapping scopes, and missing exclusions often cause routing errors that look like model unreliability.

Chapters

1. 1

   Selection and argument filling

   The tool name and its description decide which tool gets called; parameter descriptions are read afterwards, while filling a slot on a tool the model has already committed to. One sentence placed in five positions on the same agent left 336 of 340 misroutes standing in a parameter description and 14 standing when it was written into both tool descriptions. Which string a rule belongs in, and the question that decides it.

   Read chapter
2. 2

   Examples in a tool description

   A description ending in Example: query=\"status:open AND assignee:me\" survived a parser migration nobody thought to grep for, and the tool was then selected correctly on 1,238 of 1,240 requests and called wrongly on all of them. A demonstration is in-context conditioning, not documentation that ages quietly: a corrective sentence in front of the stale example recovered 6 calls in 200, and deleting the example recovered 189.

   Read chapter
3. 3

   Partitioning a confusable pair

   get_customer reads the CRM and lookup_account reads the billing platform. Both descriptions are accurate, current and well-exampled, and the agent routes correctly on 71% of 600 labelled support requests. Find the axis in the contested traffic, rename first, then write the boundary into both descriptions with an explicit handoff — 71% to 78% to 93% to 95%, and the ten-point gap that a one-sided rewrite leaves on the table.

   Read chapter
4. 4

   Negative criteria and preconditions

   send_invoice_reminder fired 118 times in a fortnight and 23 of those calls carried an invoice_id that had never appeared in the conversation, assembled from the format the description itself demonstrated. A provenance rule in the tool description took invented ids from 23 to 1; a first draft phrased as certainty cut reminders actually sent by 47%. Which prohibitions the model can act on, and which it answers by guessing.

   Read chapter
5. 5

   Tool block cost and caching

   Forty tools at 6,000 tokens across a twelve-turn conversation is not 6,000 tokens; it is 72,000, because the Messages API holds no state and the whole block goes back with the transcript. The arithmetic on 300,000 sessions a month, then the caching claim taken apart: cached input is discounted rather than removed, $56,700 becomes $10,328 at best and $28,958 when users think, and the context window the block occupies takes no discount at all.

   Read chapter
6. 6

   Compressing a tool description

   A 180-word description cut to 45 scores 94% on a 500-request eval, and so does the original — because 84% of that sample routes on the tool name alone. The only measurement that discriminated was a six-point gap on one confusable pair worth 3% of traffic, which is 0.9 requests and less than the aggregate's own noise floor. How to stratify an eval so it can see the slice, and which clauses in a description are load-bearing.

   Read chapter
7. 7

   The limits of exclusion clauses

   Twenty-three wrong-tool bugs closed by adding a sentence each, and get_account_summary now carries a 211-word description of which 140 words are prohibitions naming five siblings. Exclusions are per pair and pairs grow quadratically, so those paragraphs are a measurement of cluster density stored as prose. Three checks that separate a description bug from an architecture bug, what breaks first, and four gates a twenty-fifth tool has to clear.

   Read chapter