Designing tools models can actually use

Lesson 2 of 5 in Tools and Tool Use: The Contract Between Model and World.

If the contract is the only documentation the model reads, then tool design is the real skill of agent building — more leverage than prompt tweaks, more leverage than swapping models. Practitioner guidance across the industry has converged on the same finding: agents fail at tool selection and tool invocation far more often than at reasoning, and both failures trace back to contracts written for humans instead of models.

A useful mindset: you are not documenting an API. You are writing the words that a language model, mid-loop, with no ability to ask follow-up questions, will use to make a routing decision in a single forward pass.

Names that route

The name is the model’s first filter. verb_object names that say what the tool does — lookup_order, create_ticket, search_knowledge_base — let the model shortlist correctly before it reads a single description.

Weak names fail in two directions. Too vague (query, process, do_task) and the model cannot tell when the tool applies. Too clever (hermes, ox_v2) and internal project names mean nothing to a model that has never attended your standups.

Consistency routes too: if one tool is get_user and its sibling is fetchCustomerRecord, the model has to learn two naming dialects to see that they are related.

Descriptions that say WHEN

Most descriptions say what a tool does. Good descriptions say when to use it — and when not to:

“Search the internal knowledge base for company policies, product specs, and how-to guides. Use this before answering any question about internal matters. Not for general web facts — use search_web for those.”

That one sentence pair does what no amount of implementation quality can: it draws the boundary between this tool and its neighbours. If two of your descriptions could plausibly answer the same request, the model will split its choices between them — that failure gets a whole lesson later in this module.

Parameters that constrain

Every parameter is a place the model can go wrong, so give each one three things:

A real type. enum: ["standard", "express", "overnight"] beats shipping: string — the model literally cannot invent a fourth shipping tier.
A description with the WHY. “Set true only when the user asks what the order contains” prevents the model from setting every optional flag defensively.
One example value. "e.g. 'ORD-2026-114873'" teaches a format in five tokens. Without it, the model back-fills the format from training-data averages — and 2026-03-05 silently becomes March 5th.

And keep required parameters minimal: every extra required field is another argument the model must produce correctly on the first try.

The same tool, written for humans vs written for the model
Contract element	Written for humans (weak)	Written for the model (strong)
Name	`query` — “everyone on the team knows what it does”	`search_knowledge_base` — a stranger (the model is one) can route on the name alone
Description	“Queries the system.” What it does, restated.	“Use when the user asks about internal policies… Not for web facts — use `search_web`.” When to use it, and when not.
Parameters	`input: string` — one free-form field, formats explained in a wiki the model cannot read	Typed fields, enums for closed sets, one example value each, minimal `required` list
Failure it causes	Wrong tool chosen, invented formats, defensive flag-setting	Wrong calls rejected by schema validation before your code runs

Key terms: parameter schema, structured outputs, non-determinism, context window

Interactive checkpoint quiz (2 questions) — open this page in a browser to take it.