Designing a tool the model can use

Why it matters

The model knows a tool only from its name, its description and its schema. It cannot read the source, ask a colleague or try it in a REPL first. So the definition is a prompt, and a vague one fails the way a vague prompt fails: wrong tool chosen, arguments guessed, results misread. Most "the agent is unreliable" tickets trace back to a tool that was written as if a programmer would call it. Interviewers ask about tool design because it separates people who have shipped an agent from people who have wired one up.

The idea

Picture the reader of your definition: very fast, very literal, with no memory of the last time it used the tool. That reader needs four things. To know when the tool applies. To fill the arguments without guessing. To understand what came back. To recover when something fails.

The name and the description

Name the tool for the action it performs, verb first: search_tickets, create_event, read_file. Avoid names that describe the backend (zendesk_api) or the data (tickets). The description says what the tool does, when to use it, and when not to, in that order. "Search support tickets by free text. Use when the user describes an issue but gives no ticket number. Do not use when you already have the id; call get_ticket instead." That last sentence stops more mis-selection than anything you could add to the system prompt.

Arguments

Keep arguments few and typed. Every parameter gets a description with an example value, because the model copies the shape of an example far more reliably than it infers one from a type. Closed sets become enums: a status of open, pending or closed rather than a free string the model will spell six ways. Prefer absolute references over relative ones: an order id rather than "the latest order", an absolute path rather than one relative to a working directory the model cannot see, an ISO timestamp rather than "tomorrow". This is the manufacturing idea of poka-yoke: shape the part so it cannot be fitted the wrong way round. If the model cannot express a mistake, it cannot make it.

{
  "name": "list_events",
  "description": "List events in a time window. Call before create_event to check for clashes.",
  "input_schema": {
    "type": "object",
    "properties": {
      "calendar_id": { "type": "string", "description": "e.g. cal_work" },
      "from": { "type": "string", "description": "ISO 8601, e.g. 2026-11-13T09:00:00Z" },
      "to": { "type": "string", "description": "ISO 8601, exclusive" }
    },
    "required": ["calendar_id", "from", "to"]
  }
}

Results

A tool result is the model's only view of what happened, and every token of it is paid for and competes for attention. Return the least the model needs, structured, with the next step obvious. Three fields and an id beat a raw payload of forty. When a result is long, summarise and hand back a handle: "212 rows, first 20 shown, call again with offset=20". Return errors as information, not exceptions. A tool that raises crashes the runtime or aborts the turn; a tool that returns "calendar cal_work not found; known calendars: cal_work_2, cal_personal" lets the model fix its own call. Error text is a prompt too.

Orthogonal, and tested

Keep tools orthogonal. Two tools that overlap force a choice the model will get wrong some fraction of the time; one tool that does two things needs a mode flag the model will forget. Then test the way a product team tests a screen: run the tool on many inputs, read the transcripts, and study the model's mistakes, because each one is the description telling you what it failed to say. The agent-computer interface deserves the care a human interface gets, and for the same reason: the user cannot see the code.

Trade-offs

Richer descriptions cost tokens on every request, so a catalogue of a hundred tools with paragraph descriptions needs tool search or dynamic loading, which the Context engineering lesson covers. Enums and strict schemas stop bad calls but also stop legitimate ones you did not anticipate. Absolute references push lookups onto the model, which must now call list_calendars before list_events, one more lap of the loop. Concise results hide detail the model occasionally needs, so give it a way to ask for more rather than returning everything every time.

In an interview

The sentence to deliver: "I treat a tool definition as a prompt: the description says when to use it and when not, every argument has an example, closed sets are enums, and errors come back as text the model can act on." At junior depth, know that name, description and schema are all the model sees. At mid depth, explain poka-yoke arguments, result shaping and errors as data. At senior depth, talk about catalogue size, orthogonality, and testing tools empirically against transcripts with a tool-call accuracy metric. Expect the follow-ups: "How would you know a description is good?" (measure tool-call accuracy on a held-out task set and read the failures) and "What goes in the result when the list is huge?" (a page plus a cursor, and a count).