Design Tools for the Model

Picture two tools in the same agent. One is called billing_search, described as "search records." The other is support_search, also described as "search records." A user asks why a refund has not arrived, the model picks the billing tool, queries the wrong system with a well-formed call, and gets a clean, confident, useless answer back. Nothing crashed. The implementation of both tools may be excellent. The failure happened earlier, in the four lines of text the model was given to choose between them.

That is the part of tool design teams underinvest in. A model never reads your code. It reads a name, a description, a schema for the arguments, and later, whatever the call returns. Everything it decides (which tool, with what inputs, and what to make of the result) is decided from those surfaces. Anthropic puts the underlying shift well in its guide to writing effective tools: a tool is a contract between a deterministic system and a non-deterministic agent, and the agent is free to call it, ignore it, or ask a question instead. You are not writing a function signature for a compiler. You are briefing a capable colleague who will improvise.

The Model Context Protocol makes the surface explicit. In that specification, at its core, a tool is a name, a description, an input schema, and optionally an output schema, and tools are model-controlled: the model discovers them and invokes them on its own reading of the request. There is no other channel. If the boundary between two tools matters, it has to be visible in what the model can read.

The name does the first sort

Before any description is read closely, the name is doing selection work. search tells the model almost nothing. support_tickets_search tells it which system, which records, and which job. Anthropic’s guidance is to namespace by service and resource, with examples along the lines of asana_projects_search versus asana_users_search, so that two tools with the same verb stop looking interchangeable. One honest caveat from the same source: whether a prefix or a suffix scheme tests better varies by model, so treat your naming scheme as something to measure, not a style rule to copy from a blog post. Ours included.

Names also fail in the other direction. A name that promises more than the tool does (get_full_customer_profile that returns only an email address) teaches the model to trust the label and stop checking the result. The name is a claim. Keep it to what the tool actually returns.

Write the description for a reader who cannot ask you anything

Both major guides land on the same test, from opposite directions. Anthropic says to describe the tool as you would to a new hire, making the implicit knowledge explicit: query syntax, vocabulary, how the underlying resources relate. OpenAI’s version is the intern test: could a person use the function correctly given only what you gave the model? If not, the questions they would ask you are exactly what belongs in the description.

In practice that means the description carries four things most API documentation leaves out. When to use the tool. When not to, including which neighbouring tool to prefer. What each parameter means in the domain’s terms, with user_id instead of a bare user. And what the result will look like, so the model can plan its next step before it calls.

This is not polish. Anthropic reports that precise refinements to tool descriptions took Claude Sonnet 3.5 to state-of-the-art performance on SWE-bench Verified, and that a separate production problem, the model appending the current year to search queries and biasing the results, was corrected by improving a description, not by changing code. When a model misuses a tool in your own traces, read the description before you read the implementation. A good share of the time, the model did what the text told it to do.

Let the schema refuse bad calls

A description persuades. A schema constrains, and the constraint is the more reliable of the two. Where a value comes from a known set, an enum says so; two booleans that can contradict each other invite a call that is valid JSON and nonsense at the same time. Required fields should be the ones the tool genuinely cannot run without, and optional fields should be ones the model can sensibly omit.

Two moves save more failures than any amount of description tuning. First, do not ask the model for a value your code already knows. If the run is already working on order 8819, that order ID belongs in your code path, not in a parameter the model can mistype. Second, fold steps that always happen together into one tool. A lookup that is always followed by a second lookup is really one tool split in two, and every seam between the halves is a place for the model to stop early, reorder, or pass the wrong identifier across. Anthropic makes the same point with its own examples: a search_contacts over a list_contacts the agent then has to page through, a single scheduling tool over separate list-and-create calls.

The result is an interface too

What comes back gets the same design attention, because the result is what the next decision is made from. Return the fields the next step needs, in the form a reader can act on. Anthropic found that resolving cryptic identifiers into meaningful names measurably improved precision on retrieval tasks, and it recommends letting the agent choose the shape of the answer: a response_format option returning a detailed response at 206 tokens or a concise one at 72. The point is not the specific numbers. It is that verbosity is a parameter the caller controls, not a fixed cost every call pays.

Truncation deserves the same care. A result cut off mid-list with no note teaches the model the list ended. A result that says it was truncated, and that a narrower query would return the rest, gives the model a next move. The result is the only feedback the model gets about your system. Write it like it will be believed, because it will be.

Where better text stops helping

None of this fixes a tool that should not exist. If two tools genuinely do the same job, no description will keep them sorted for long; merge them. If a tool hands the model authority it should not have, a clearer description makes misuse more reliable, not less. And descriptions are not free: they sit in the context of every run, so a description that grows by accretion, every past incident pasted in as a warning, eventually costs more attention than it saves. OpenAI’s guide adds a related caution: examples help many models use a tool correctly, and can hurt performance with reasoning models. There is no universal template. There is a prototype, an evaluation with real multi-step tasks, and the willingness to edit the text when the traces say the text is wrong.

So review a tool the way its reader meets it. Cover the implementation. Read the name, the description, the schema, and a sample result, and ask whether a smart stranger could pick the right moment, fill in the right arguments, and understand what came back. If they could not, the model cannot either. It will just fail faster, and at greater scale.

Work with us

If your agents pick the wrong tool, fill in plausible-but-wrong arguments, or drown in their own results, the fix usually starts at the tool surface, not the model. Bring the tool set through Trida AI’s intake and we will review it the way the model reads it.