Tool design that agents can use

Tools built for humans and tools built for agents fail differently. A human explores, reads docs, and learns from mistakes. An agent gets one description and a schema, and has to be right immediately.

Name for the job, not the implementation

query_db tells the model nothing about when to reach for it. find_customer_by_email does.

Specific names also stop the model reaching for a general tool when a precise one exists.

Put the trigger in the description

Every description should answer two questions: what does this do, and when should I use it.

Weak: "Searches the index."

Strong: "Search product documentation by keyword. Use when the user asks how a feature works. Returns the three most relevant sections with their headings."

That last clause matters too. Saying what comes back stops the model calling it speculatively to find out.

Constrain arguments in the schema

Anything you express in the schema does not have to be enforced in prose:

{
  status: z.enum(["open", "closed", "pending"]),
  limit: z.number().int().min(1).max(100).default(20),
}

An enum makes an invalid status impossible. A max stops the model asking for 10,000 rows. A default removes a decision it might get wrong.

Free form strings are where wrong arguments come from. Narrow them whenever the domain is genuinely narrow.

Few tools, well chosen

Twenty overlapping tools is worse than five clear ones. Every extra tool adds schema tokens to every request and adds another chance to pick the wrong one.

If two tools are distinguished only by a flag, make it one tool with a parameter.

Design the output for a reader with no memory

Return what is needed to act, in a shape that survives being read once.

Include identifiers the model will need for the next call. Label fields. Prefer a short structured summary over a raw dump. If results are truncated, say so explicitly, or the model will treat a partial list as complete.

Errors should teach

This is the single highest leverage thing in tool design.

• Bad: Error: 400
• Good: Invalid date format. Use YYYY-MM-DD, for example 2026-07-26.

The good version ends the loop on the next call. The bad one produces three identical retries and a confused apology.

Make destructive things hard to reach

If a tool can delete or overwrite, require an explicit identifier rather than accepting a filter. delete_user(id) is recoverable from a mistake. delete_users(where) is not.

Offer read only variants. Most agent work is reading, and a read only tool cannot be talked into anything.

The test

Hand your tool list to someone who has never seen the system, with no documentation beyond the descriptions. Ask them which tool they would use for a given task.

If they hesitate, the model will too, and it will not ask.