Kairox Arch Prep
STUDY NOTES · LESSON 5 OF 12 · 6 MIN READ

Designing tools Claude can use well

How to write tool names, descriptions and parameters Claude chooses correctly, keep results small, and return errors an agent can recover from.

In 30 seconds

  • Descriptions are prompts: say what the tool does, when to use it instead of a similar tool, and what comes back.
  • Fewer, task-shaped tools beat dozens of narrow ones.
  • Validate inputs in the handler every time; the schema guides but does not protect.
  • Results should be bounded, and errors should say what happened and what to do next.

Anatomy of a good tool definition

{
  "name": "find_customer",
  "description": "Look up one customer by email or phone. Use this before
     any order or refund tool. Returns id, name, plan and status.
     Use search_customers for partial names instead.",
  "input_schema": {
    "type": "object",
    "properties": {
      "email": {"type": "string", "description": "Exact email, e.g. ana@example.com"},
      "phone": {"type": "string", "description": "E.164 format, e.g. +84912345678"}
    }
  }
}

Claude picks tools from their names, descriptions and parameters, so write them like documentation for a new colleague. The most useful sentence is often the one that separates this tool from a similar one: "use this, not that, when…".

Fewer, better tools

Every definition costs context and adds a decision. Sixty tools that mirror database tables ask Claude to think like your schema. Five tools shaped around real tasks — find a customer, summarise an account, issue a refund — match how people ask. Overlapping tools should be merged, with an explicit parameter for the mode.

Inputs: guide with the schema, enforce in the handler

Use types, enums for fixed choices and per-field descriptions with formats and examples. Mark only truly required fields as required; forcing optional ones pushes the model to invent values. Then re-validate everything in the handler — type, range, business rules and permissions — because any model output, or injected text, can be wrong.

The four kinds of result a well-designed tool returnsClaude callsget_customerYour handlervalidates, then runsokfiltered, paginated datanot_foundsay so + suggest next steptransient errortimed out · retry is safeinvalid inputwhich field, and why
Every outcome tells Claude what happened and what to do next. Ambiguous results cause blind retries and wrong answers.

Outputs: small, labelled and honest

A tool that returns 5,000 rows floods the context window. Add filters and pagination with sensible defaults, and return counts or summaries for large results along with how to get more. Label units and keep them consistent.

Errors are part of the interface

"Error 0x8F2" tells an agent nothing, so it retries. Make the outcome explicit: not found (and what to try next), a transient failure that is safe to retry, or invalid input with the field that was wrong. That one distinction — retryable or not — prevents most agent loops.

Part of Domain 2: Tool Design & MCP Integration (18% of the exam). Explanations are our own, checked against Anthropic's documentation on November 22, 2026.

Common traps

TrapWhy it failsDo this instead
One-line descriptions on similar toolsClaude cannot tell when to use whichExplain purpose, the difference, inputs and returns
Returning every rowFills the context window and dilutes attentionFilter, paginate, summarise
Opaque error codesClaude retries blindlySay not_found, transient or invalid — and the next step

Check yourself

Two original practice questions on this lesson. Try them before opening the answers.

Check yourself 1

Scenario: Customer support resolution agent

Claude keeps choosing the wrong tool between search_orders and get_order. Both have one-line descriptions. What is the most effective fix?

  1. A. Expand each description: purpose, when to use it over the other, parameters, returns
  2. B. Merge them into one generic order tool with a free-text "query" parameter
  3. C. Tell Claude in each user message which of the two tools it should call
  4. D. Rename the tools to search_orders_v2 and get_order_v2 so they look more distinct
Show answer and explanation

Answer: A. Tool descriptions are the main signal Claude uses to choose, so they should read like documentation for a new colleague, including how to choose between similar tools. Cosmetic renames add no information, a vague merged tool moves the ambiguity into a free-text field, and naming the tool in every message defeats the purpose of tool use.

Check yourself 2

Scenario: Customer support resolution agent

A lookup tool returns the string "Error 0x8F2" when a customer is not found. Claude retries the same call repeatedly. How should the tool's error response be designed?

  1. A. Return the same generic "request failed" message the tool uses for timeouts
  2. B. Return the full stack trace so Claude has the complete technical detail to work with
  3. C. Raise an exception so the orchestrator stops the loop and reports a system failure
  4. D. Return an explicit not_found outcome for that email, suggesting the user confirm it
Show answer and explanation

Answer: D. Errors are part of the tool interface. An explicit outcome that distinguishes "not found" from "system failure" and suggests a next step lets the model recover instead of retrying blindly. A generic failure message looks like a timeout and invites retries; stack traces are noise (and may leak internals); crashing the loop turns a normal case into an outage.

Keep going