What Makes a Good Tool for an AI Agent?

What makes a good tool for an AI agent?

As of September 2026, the consistent answer from the people building these systems is: fewer tools, each matching a whole task rather than an API endpoint, returning results a human could read. The instinct to wrap every endpoint you have produces an agent that technically can do everything and reliably does nothing.

This has quietly become the most important skill in building automations, and almost nobody discusses it. Teams spend weeks on prompts and about an hour on the tools, when the tools are what the agent actually acts through.

The good news is that the guidance is now written down by the parties with the most data, and it is unusually specific. Here is what it says and how we apply it.

Why do more tools make an agent worse?

Because tool selection is itself a decision the model has to get right, and every additional option makes it harder. Anthropic's engineering guidance on writing tools for agents, published on September 11, 2025, states it plainly: more tools do not always lead to better outcomes.

Its recommendation is to focus on high impact workflows rather than wrapping every endpoint. The worked example is a scheduling tool. Instead of exposing separate tools to list users, list events and create an event, expose one tool that schedules an event and handles availability internally.

That is the whole idea in one example. The agent should not have to orchestrate three calls to accomplish something a person would describe as one action. Each hop is a chance to choose wrong.

How should tools be named?

With namespaces, and more carefully than you would name an internal function. Anthropic recommends namespacing tools by service and by resource, giving examples like asana_search and jira_search, and notes that whether the namespace goes at the start or the end has non trivial effects on tool use evaluations.

That last detail is worth pausing on. The position of a prefix measurably changes behaviour, which tells you how much the model is reading the name itself rather than only the description.

Parameter names matter for the same reason. The guidance is to avoid ambiguity, preferring user_id over user, because a parameter called user invites the model to pass a name where an identifier is required.

What should a tool return?

Something the model can reason about, not something a database would emit. Anthropic's advice is to prioritise contextual relevance over flexibility and to avoid low level technical identifiers, noting that using semantic names instead of cryptic identifiers significantly improves precision in retrieval tasks by reducing hallucinations.

This is the single change we see improve automations most. A tool returning a list of UUIDs forces the model to guess which one it wants. The same tool returning names, titles and dates lets it choose correctly and then explain its choice.

The test we use: could a competent new colleague act on this response without opening your database? If not, the model cannot either, and no amount of prompt instruction fixes it.

How do you keep tool responses from eating the context window?

Build the limits into the tool rather than asking the model to be brief. Anthropic recommends pagination, filtering and truncation with sensible defaults, and offering a response format option with detailed and concise modes. It reports that the concise format used roughly one third of the tokens of the detailed alternative.

A third is a large saving for a change that takes an afternoon, and it compounds on every call in a long running task.

Set the concise mode as the default and let the agent ask for detail. Defaults are decisions, and a verbose default is a decision to spend tokens on data nobody looked at, which is the quiet part of the cost problem.

What does the MCP specification require?

The Model Context Protocol specification dated June 18, 2025 defines a tool as a name, an optional human readable title, a description, an input schema, an optional output schema, and optional annotations describing the tool's behaviour.

The output schema is the field most often skipped and most worth filling in. The specification says that if an output schema is provided, servers must return structured results conforming to it and clients should validate against it. That turns a malformed response into a caught error instead of a confident wrong answer.

The specification also separates two kinds of failure: protocol errors for unknown tools or invalid arguments, and execution errors reported in the result with an error flag set. Distinguishing them matters, because one means the agent called something wrong and the other means the world pushed back.

If you are standing up a server rather than just consuming one, the surrounding decisions are covered in MCP servers for web teams.

What should a tool never decide on its own?

Anything a person would want to approve. The MCP specification is direct about this: for trust, safety and security there should always be a human in the loop with the ability to deny tool invocations, and applications should make clear which tools are exposed, show visual indicators when tools are invoked, and present confirmation prompts.

Build that at the tool boundary rather than in the prompt. A tool that writes to a system of record should require an approval token it cannot mint itself. That is a control. An instruction telling the model to ask first is a preference.

The specification's client guidance goes further and recommends showing tool inputs to the user before calling the server, specifically to avoid malicious or accidental data exfiltration. Accidental is doing real work in that sentence.

How much should you trust a tool you did not write?

Less than the protocol's convenience suggests. The specification warns that clients must consider tool annotations untrusted unless they come from trusted servers. The metadata saying a tool is read only is supplied by the same party that supplies the tool.

Our rule is that a tool's own description of itself never decides its permissions. Permissions come from the credentials you issue it, which is the only layer the tool cannot talk its way around.

This connects to the wider problem of content influencing an agent's behaviour, which we covered in prompt injection in real automations.

What does the specification require on the server side?

Four things, stated as requirements rather than suggestions: validate all tool inputs, implement proper access controls, rate limit tool invocations, and sanitise tool outputs. Clients are additionally advised to validate results before passing them to the model, implement timeouts, and log tool usage for audit purposes.

Rate limiting is the one teams skip. An agent in a retry loop can call a tool far more often than a human ever would, and the first time you discover this is usually on someone else's invoice.

Logging is the one they regret skipping. When an agent does something surprising, the tool call log is the only record of what it actually did, as distinct from what it said it did.

Why does this matter more as your stack grows?

Because the number of systems an agent could touch keeps rising. Zylo's 2026 SaaS Management Index reports that the average company manages 305 SaaS applications, and that marketing teams alone use an average of 103 marketing related applications.

If tool design were a matter of wrapping endpoints, that number would be a roadmap. It is not. It is an argument for choosing the handful of workflows that matter and building one good tool for each.

The discipline is the same one that makes a good internal API: name the job, not the mechanism. An agent given schedule_meeting and publish_post will outperform one given forty endpoint wrappers, every time.

How should you audit the tools you already have?

Take your agent's tool list and read it as a stranger would. Mark every tool whose name does not say what it does, every response containing an identifier a human could not interpret, and every tool that can change something without an approval step. Those three passes will find almost everything.

Then check the count. If your agent has more than about ten tools and is not reliably choosing the right one, consolidating is a more promising fix than rewriting the prompt, and it is the one teams try last.

Make the output schemas explicit while you are in there, since that is what lets you validate rather than hope, and it pairs with the wider case in using structured outputs in automations.

What is the summary?

Tools are the interface between a model's judgement and your systems, and they deserve the care you would give a public API. Fewer tools, named for jobs, returning readable results, with schemas you validate and approvals you enforce outside the model.

None of this is speculative. It is written down in the MCP specification and in published engineering guidance, and it is mostly ignored because tool design looks like plumbing rather than product work.

We build these automations for B2B teams alongside the websites and CRMs they act on, so we usually meet the tool layer when something has gone wrong in it. If you want a review of what your agents can currently reach and how well described it is, we are happy to look. You can find us at phoenix.studio.