Designing Tools

Time: ~12 minutes. Tangible win: write a tool definition that an agent uses correctly on the first attempt, and recognize the three defects that cause most misuse.

A tool is the agent's only way to act on the world, and the model reads its definition to decide when and how to use it. Anthropic describes this as the agent-computer interface, and says it deserves the same care as a human-computer interface. Most failures that look like model problems are tool design problems.

Primary source Building effective AI agents, Appendix 2: Prompt engineering your tools. Read it in full. It is short and includes the file path example that is worth remembering.

Five parts of a good tool

Each tool definition is a contract. Treat it like a docstring you would write for a new engineer joining the team.

  1. Name. Use a verb and a noun that describe one action, such as get_invoice.
  2. Description. Say what it does, when to use it, and when not to use it. Naming the alternative tool prevents confusion.
  3. Parameters. Describe each one with its format and an example. Ambiguous names invite wrong arguments.
  4. Return value. Return only what the next decision needs. Large raw payloads waste the context budget.
  5. Errors. Return a message that says what went wrong and what to try next.
{
  "name": "get_invoice",
  "description": "Fetch one invoice by its ID. Use when the user gives an invoice number such as INV-2026-0042. Do not use to search by customer; use search_invoices for that.",
  "input_schema": {
    "type": "object",
    "properties": {
      "invoice_id": {
        "type": "string",
        "description": "Invoice ID in the form INV-YYYY-NNNN"
      }
    },
    "required": ["invoice_id"]
  }
}

Notice what the description does. It states the trigger, the boundary with a neighboring tool, and the expected input format. An engineer reading only this definition could call the tool correctly.

Make mistakes hard to make

Anthropic calls this poka-yoke, after the manufacturing practice of designing errors out. The SWE-bench team found that an agent made mistakes with relative file paths once it had moved out of the root directory. They changed the tool to require absolute paths, and the model used the new form without error. Ask yourself which argument the model could get wrong, then change the tool so that the wrong value is impossible or rejected with a clear message.

Overlapping tools are the common failure If a human engineer cannot say which tool to use in a given situation, the agent will not do better. Merge tools that do the same job, or sharpen the descriptions until the boundary is obvious.

Practice

  1. Take a function you already have in your codebase. Rewrite its description following the five parts above.
  2. Give the tool five realistic inputs, including one with a typo and one that should fail. Record each mistake the model makes.
  3. Change one thing per iteration, such as a parameter description or an error message, and rerun the five inputs. Keep the change only if the mistakes drop.

Retrieval check

Two tools overlap in purpose, and the agent sometimes picks the wrong one. What is the first fix?

Correct. Overlap is a defect in the interface. Clarify the boundary in the tools themselves before adding instructions around them.

Not quite. A raised step limit or more prompt text will not fix an ambiguous choice. The boundary belongs in the tool definitions.

A lookup tool finds no matching record. Which result should it return?

Correct. An actionable message lets the model recover, for example by searching instead. An empty string gives it nothing to reason about.

Not quite. A silent or fatal result leaves the model without a path forward. A clear message that names the next step lets it recover.

Ask the agent: "Review this tool definition for overlap and missing error cases: [paste a tool]." Next lesson looks at what goes into the context window, since every tool result competes for the same budget.