Designing tools a model can use
A tool is a contract between a deterministic program and a model that reads English. Most agent failures I see are tool failures wearing a model's face: the schema was vague, the output was enormous, or the error said "failed". Design tools the way you would design an API for a smart colleague who cannot ask you questions.
Fewer, bigger, clearer
The model has to pick the right tool from its description alone, so every tool you add makes the choice harder and the prompt longer. Two habits fix most of it.
Match the task, not the database. An agent that schedules meetings needs schedule_meeting(attendees, duration, window), not list_users, list_events and create_event for the model to stitch together across six turns. Wrap the chain inside one tool and let deterministic code do the joining. Fewer steps means less cost, less latency and fewer chances to go wrong.
Name the intent and namespace the family. search_docs and search_tickets beat two tools both called search. Prefixes keep related tools grouped when a model sees forty of them.
What to put in the definition
- A description written like onboarding. What it does, when to use it, when not to, and what it returns. Two or three plain sentences beat a keyword list.
- Unambiguous parameter names.
user_emailbeatsuser. Use enums for closed sets. Mark required fields. Add one example value in the parameter description. - Strict schemas. Reject unknown fields and wrong types before you run anything. Some APIs can enforce your schema at generation time; validate again anyway.
- Responses made for a reader. Return names and short descriptions, not opaque UUIDs. Offer a
response_formatofconciseordetailedso the model can ask for more. - Output limits with guidance. If you truncate, say so and say how to get the rest: "Showing 20 of 340 results. Narrow with the
queryparameter or passcursor=20." - Errors that teach. "Invalid date" teaches nothing. "date must be YYYY-MM-DD, for example 2026-03-14; you sent 'next Friday'" fixes itself on the next turn.
The hidden tax of schemas
Tool definitions ride along on every request. If one schema costs about 200 tokens and you expose 40 tools:
$$\text{overhead} = 40 \times 200 \times 20 \text{ steps} = 160{,}000 \text{ input tokens per run}$$
That is before the agent has read a single file. Cache the tool block, keep the order deterministic so the cache survives, and delete tools the task does not need. Some platforms can also load tool definitions on demand; a retrieval step over tool descriptions is the same idea as week 4 applied to your own tool list.
In code
SEARCH_TICKETS = {
"name": "tickets_search",
"description": (
"Search support tickets by text and optional status. Use this to find prior "
"reports before filing a new one. Returns up to 20 tickets, newest first. "
"Do not use it to read a single ticket; use tickets_get for that."
),
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "Keywords, for example 'login timeout'"},
"status": {"type": "string", "enum": ["open", "closed", "any"]},
"response_format": {"type": "string", "enum": ["concise", "detailed"]},
"cursor": {"type": "integer", "description": "Offset from a previous truncated result"},
},
"required": ["query"],
"additionalProperties": False,
},
}
def tickets_search(query, status="any", response_format="concise", cursor=0):
if status not in {"open", "closed", "any"}:
raise ValueError("status must be one of open, closed, any")
rows = db.search(query, status)
page = rows[cursor : cursor + 20]
lines = [f"#{r.id} [{r.status}] {r.title}" for r in page]
if response_format == "detailed":
lines = [f"{line} | {r.owner} | {r.summary[:200]}" for line, r in zip(lines, page)]
footer = ""
if len(rows) > cursor + 20:
footer = f"Showing {cursor + 1}-{cursor + 20} of {len(rows)}. Pass cursor={cursor + 20} for more."
return "\n".join(lines + [footer]) if page else "No tickets match. Try fewer or broader keywords."
Notice the empty-result message. "No tickets match" with a suggestion keeps the model moving; an empty string makes it guess.
Evaluate tools like code
Write ten realistic tasks that need your tools. Run them. Read the transcripts, not just the scores: look for repeated calls with the same arguments, calls to the wrong tool, retries after a vague error. Each pattern is a fix in a description, a schema or a message. Change one thing, rerun, keep what helped. This is the loop from week 8 applied at the smallest scale.
Common mistakes
- Wrapping every REST endpoint as its own tool. Your API is not the model's task.
- Returning raw JSON blobs with 40 fields when the model needs three.
- Overlapping tools whose descriptions do not say when to prefer each.
- Side effects hidden inside a tool called
get_something. Name writes as writes. - Letting a tool return unbounded text. One 200,000-character page can wipe out the context window.
Check yourself
- Rewrite three chained low-level tools into one task-level tool. What logic moves into code?
- Give an error message for a bad date that lets the model fix its own call.
- Why does tool order matter for caching?
- What would you log to find out a tool description is misleading the model?