Designing Tools Agents Can Use

Picture how the agent actually sees your tool. It never runs your code to find out what it does; it reads the words you wrote — the name, the description, the parameter list — sitting right there in its context alongside the system prompt. From the model's point of view, a tool is a paragraph it has to interpret, not a function it can inspect. That single fact reframes the whole job.

Here is the mental model that changes everything: a tool definition is not API documentation for humans — it is a prompt for the model. Every tool's name, description, and parameter schema is loaded into the agent's context on every call. The model reads them to decide which tool to use and how to fill it in, exactly the way it reads your system prompt.

That reframing has teeth. In 2025, Anthropic published Writing effective tools for AI agents making the case directly; the same year, a paper on rewriting tool descriptions (arXiv:2602.20426) showed that on catalogs of 100+ tools, improving descriptions alone produced consistent, significant gains in tool-selection accuracy and end-to-end task success. The tool's implementation never changed — only the words the model reads.

So the craft of tool design is the craft of writing for a model: clear names, an unambiguous description, a schema that makes wrong inputs impossible to express, and outputs sized for a context window. Get the wording right and a mediocre model uses your tools reliably. Get it wrong and your best model fumbles. Everything in this lesson follows from treating the tool surface as prose the model must understand under pressure.

Think of the name and description as the only briefing the model gets before it has to act. If a smart new hire couldn't pick the right tool from those words alone, neither can the model — so write them like instructions, not labels.

Start with the name. Use snake_case, consistently, and name the action the model is taking: search_invoices, send_email, cancel_subscription. For larger tool sets, namespace with a prefix or suffix — asana_search, jira_search — so related tools cluster. Anthropic notes the prefix-vs-suffix choice has a measurable effect on tool-selection scores, so pick one convention and hold it.

The description is a mini-prompt. A reliable template:

"Tool to <do X>. Use when <Y>. Do not use for <Z>."

State the critical constraint first, keep it under ~1024 characters, and remember every character costs tokens on every call. Spell out what the model can't infer — units, formats, side effects, and when not to reach for this tool. OpenAI suggests the intern test: could a competent new hire, with no other context, pick the right tool from your description alone?

@tool
def refund_payment(payment_id: str, amount_cents: int) -> str:
    """Issue a refund for a completed payment.

    Use when a customer is owed money back on a settled charge.
    Do NOT use for disputes or chargebacks (use open_dispute).
    amount_cents must be <= the original charge. Idempotent per
    (payment_id, amount_cents).
    """

How many tools should an agent have, and how big should each one be? This is a Goldilocks problem, and both extremes fail in opposite ways — flood the model with choices, or hand it one blunt instrument it has to wrestle.

The first mistake is too many tools: wrapping every API endpoint 1:1 gives you fifty overlapping functions whose descriptions blur together. Every one is read on every turn — inflating cost and latency — and selection accuracy collapses. OpenAI's guidance is to keep the active set under ~20 tools per turn and defer the rest with dynamic loading or a tool-search step. As catalogs pass 50–150 tools, the model leans on embedding similarity, and a poorly described tool becomes indistinguishable from the right one.

The second mistake is too few, too coarse: a single manage_files(action, ...) god-tool forces the model to encode intent into stringly-typed arguments it gets wrong.

The principle: each tool does one atomic action — copy_file, move_file, delete_file — but consolidate operations the agent always uses together. If the model invariably calls get_customer_by_id, then list_transactions, then list_notes, fuse them into one get_customer_context that returns all three. You've cut three round-trips to one and removed two chances to pick the wrong next tool.

The cheapest bug to fix is the one the model can't even write down. If your schema only allows valid inputs, the model physically cannot emit a malformed call — no validation, no retry, no apology needed. That is the whole goal of parameter design: shrink the space of expressible mistakes to zero.

Use JSON Schema to its fullest:

• Enums for finite value sets (status: "open" | "closed" | "refunded") — the model can't hallucinate "refunded!".
• Strong types over free strings: integers, ISO-8601 dates, booleans. Encode units in the name (amount_cents, timeout_ms).
• Explicit required/optional, with concrete examples inside each field's description.
• Strict mode on. OpenAI's strict mode (additionalProperties: false, every field marked required, null as a type for genuinely optional fields) guarantees schema adherence — no missing keys, no invented enum values.

from pydantic import BaseModel, Field
from typing import Literal

class BookFlight(BaseModel):
    origin: str = Field(description="IATA airport code, e.g. 'SFO'")
    destination: str = Field(description="IATA airport code, e.g. 'JFK'")
    date: str = Field(description="Departure date, ISO-8601 'YYYY-MM-DD'")
    cabin: Literal["economy", "business", "first"] = "economy"

LangChain, the OpenAI SDK, and Anthropic all derive their JSON Schema from models like this. Validation at the tool boundary is your last line of defense — but a tight schema means there's far less left to catch.

Whatever a tool returns isn't a log file you skim later — it's the next thing the model reads, and it shapes the very next decision. Treat every return value as a message to the agent: say the useful thing, leave out the noise, and when something breaks, tell it what to do instead of dumping the wreckage.

So return high-signal, not high-volume. Anthropic's guidance: prioritize relevance over completeness. Strip UUIDs and mime_type noise in favor of human-readable identifiers, and offer a response_format parameter (concise vs detailed) — their concise mode used roughly one-third the tokens. For large result sets, paginate, filter, or truncate (Claude Code caps tool output near 25,000 tokens by default).

Errors are the subtler art. An error message is feedback to the model, not a log line for you. A raw stack trace burns context on something the model can't act on. Structure errors so the model knows what to do next:

{
  "error_code": "AMOUNT_EXCEEDS_BALANCE",
  "context": {"requested_cents": 5000, "available_cents": 3200},
  "action": "Retry with amount_cents <= 3200, or call check_balance first."
}

That triple — a machine-readable error_code, the relevant context, and an explicit action — turns a failure into a recovery the agent can execute on its own, instead of a dead end it loops on or hallucinates around.

Here is an uncomfortable truth about agents: they retry, and they don't always know they're repeating themselves. A response times out, the loop fires the same call again, and now you've charged a customer twice. Because the model is nondeterministic, you cannot trust it to never do the dangerous thing — you have to make the dangerous thing impossible to do twice (or, sometimes, impossible to do without a human nod).

So design side-effecting tools to be idempotent: accept a large, unguessable idempotency key so a repeated call is a no-op, not a second charge.

Some actions can't be made idempotent — deleting a production table, wiring money, posting publicly. For those, separate the decision from the execution and require an explicit confirmation step or a policy-service approval gate before the irreversible action fires.

The deeper rule: safety invariants live in the tool layer, not the prompt. A system-prompt instruction like "never delete more than 10 rows" can be forgotten, overridden, or injected away over a long conversation. Enforce limits where they can't be bypassed:

• RBAC scope checks and allowlists inside the tool, on every call.
• Rate limits independent of model output.
• Sandboxing for code execution and file access.
• Least privilege — give each tool only the permissions it strictly needs.

The model proposes; the tool layer disposes — and the tool layer is the only place you can guarantee the rules hold.

You can't tell whether a tool is well-designed by rereading its description — it looks fine to you because you already know what it means. The only honest test is to watch a real agent try to use it on a real task and see where it stumbles. The good news: most stumbles point at a specific line of prose you can fix.

And not with a trivial one-call test — use realistic multi-step tasks that resemble production work, because the failures that matter show up only when tools compose.

Instrument every run and track:

Treat tool descriptions as living prompts: when an eval shows the agent picking the wrong tool, the fix is usually three better words in a description, not a new tool. The 2025 description-rewriting research formalized exactly this — curriculum-style refinement of descriptions was the single biggest lever on large-catalog reliability. Build a small eval harness early, run it on every tool change, and let the failures tell you which words to rewrite.