Claude Tool Use Best Practices for Reliable Agents

Here's the thing most people miss when an agent misbehaves: Claude never sees your implementation. It sees three things per tool — the name, the description, and the input schema. That little block of JSON is the entire contract. If it's ambiguous, the model guesses, and a guess at 2am is how you end up debugging “why did it call send_invoice when the user asked a question.”

The first agent I shipped had two tools — search_orders and get_order — with descriptions that were basically the same sentence. The model flipped between them at random, sometimes searching when it had the exact ID, sometimes fetching a single order when it needed a list. I spent an evening editing the promptbefore I realized the prompt was fine. The tools were the problem. I rewrote the two descriptions to say plainly when to use each one — and the “wrong tool” bug just stopped.

A good tool description does two jobs: it says what the tool does, and it says when to reach for it and when not to. That second half is what people skip, and it's the half that prevents overlap. If two tools could plausibly answer the same request, at least one description needs a line that pushes the model toward the other.

Compare these two definitions for the same tool:

# vague — the model will misfire
{
  "name": "get_order",
  "description": "Get an order."
}

# specific — the model knows exactly when to call it
{
  "name": "get_order",
  "description": "Fetch ONE order by its exact order_id and
    return its full details (items, status, total). Use this
    only when you already know the order_id. To find an order
    from a customer email or date range, use search_orders
    instead."
}

Same tool, same schema, wildly different behavior. Anthropic makes the same point in their tool use documentation: the description is the highest-leverage part of the whole definition. Give it three or four real sentences, not four words. This is the same “be explicit with the model” discipline I lean on when building dynamic Claude Code workflows.

The input schema isn't just validation — it's guidance. Every constraint you add is one fewer way the model can call the tool wrong. Loose schemas (“status is a string”) invite invented values. Tight schemas (“ status is one of these four”) make the invalid call impossible to express.

• Use enums for anything with a fixed set of values — statuses, categories, modes. The model can't pass a value that isn't on the list.
• Mark required fields required, and describe each parameter in one line. "email: the customer's email, lowercased" beats a bare string type.
• Prefer a few well-typed parameters over one free-text blob the model has to structure itself.
• Give examples in the description when a format is fiddly (dates, IDs) — the model copies the shape.

Then validate anyway. The schema shapes what the model tends to send; your handler still has to check what actually arrived and reject bad input with a clear message. Trusting the JSON blindly is the same mistake as trusting user input blindly — it works until the one time it doesn't.

When a tool fails, you have three options, and only one of them is any good. You can throw and kill the turn (brittle), return a raw stack trace or an empty result (the model retries blindly or hallucinates), or return a short, plain message that tells the model what happened and what to do next. Do the third.

# bad — the model can't recover from this
{ "type": "tool_result", "content": "" }

# bad — noise the model will just retry against
{ "type": "tool_result", "content": "Traceback ...
  KeyError: 'customer_id'" }

# good — recoverable, actionable
{
  "type": "tool_result",
  "is_error": true,
  "content": "No customer found for that email.
    Ask the user to confirm the address, or use
    search_customers to look them up by name."
}

Set is_errorso the model knows the call failed, then tell it the next move. This is exactly the “fail loud, fail recoverable” habit I wrote about when my n8n agents started failing silently. A silent empty result is the worst outcome: the loop keeps going, spends tokens, and produces confident nonsense.

Two levers people reach for too fast. tool_choice lets you force a specific tool or force “some tool.” It's great for a router step that must return a classification, or a final step that must record a result — anywhere the correct action is singular. For normal agent turns, leave it on auto. Forcing a tool on every turn makes the agent call tools it doesn't need, which costs tokens and adds failure surface.

Parallel tool calls are the other one. Claude can request several tools in a single turn, and for independent reads — fetch three records at once, hit two APIs that don't depend on each other — that's a real latency win. But only parallelize calls that are genuinely independent. If tool B needs tool A's output, let them run in sequence; a parallel call there just races and returns garbage. I go deeper on the cost side of this — and why transport choice matters as much as tool count — in MCP vs CLI for AI agents.

Fewer than you think. Every tool you expose is text injected into every single turn, and it's one more thing the model can pick wrong. I start with three or four and only add one when the logs show the current set can't do a real task. Twenty narrow tools is not a feature — it's twenty chances to misfire and a fat token bill on every call.

When you truly need broad capability, don't list fifty endpoints. Group them behind a few higher-level tools, or let the model write code that orchestrates the calls itself. That “give it a runtime, not a menu” move is the same reason a subagent that owns a whole subtask beats micromanaging it — which I broke down in the real token cost of Claude subagents. Anthropic's own guide to writing tools for agents lands in the same place: a few consolidated, well-described tools beat a sprawl of thin ones.

• The model reads your tool name, description, and schema — not your code. That block is the contract.
• Write each description to say what the tool does AND when not to use it. Overlap is the #1 cause of wrong-tool calls.
• Make schemas strict: enums, required fields, per-parameter descriptions. Then validate in your handler anyway.
• Return errors as tool results with is_error and a plain next step — never a stack trace or an empty string.
• Force tool_choice only when the action is singular; parallelize only genuinely independent calls.
• Keep the tool count small — three or four to start. Consolidate or hand the model code instead of listing fifty tools.