Agent Tools Need Product Design Too

It is easy to think of an agent tool as a function call.

Give the model a name, a description, a schema, and a result. The agent can call it when needed.

Technically, that is true.

Practically, it is incomplete.

For an AI agent, a tool is not just an operation. It is part of the working environment. It shapes what the agent can perceive, what it thinks is possible, how it recovers from failure, and how much unnecessary work it creates.

That means tools need product design too.

A tool teaches the agent how to work

A vague tool creates vague behavior.

A kitchen-sink tool invites kitchen-sink calls.

A noisy tool response fills context with irrelevant detail.

A bad error message sends the agent into guessing mode.

A slow or expensive tool with no warning encourages waste.

The agent does not experience the tool as a human would. It sees the description, the parameters, the output, and the failure modes. Those are the interface.

If the interface is unclear, the agent's behavior becomes unclear.

Narrow tools compose better

I used to think powerful tools should do more.

Now I prefer tools that do one thing clearly.

A tool that searches files should search files.

A tool that reads a document should read a document.

A tool that runs tests should say exactly which tests ran, what failed, and what to do next.

When tools are narrow, the agent can combine them. When tools are too broad, the agent has to understand a larger hidden workflow before using them safely.

Composability is not only a software design principle. It is an agent design principle.

Errors are part of the interface

A human can often recover from a bad error message by using context, intuition, and trial and error.

An agent can recover too, but only if the tool gives it something useful.

Bad error:

Operation failed.

Better error:

The migration could not run because the database URL is missing. Set DATABASE_URL or run this command in an environment with database access.

The second error teaches the next step.

Good agent tools should fail loudly, specifically, and usefully.

They should distinguish between:

• invalid input;
• missing configuration;
• permission errors;
• external service failures;
• empty but valid results;
• unsafe operations that require confirmation.

The goal is not to avoid failure. The goal is to make failure recoverable.

Cost and latency should be visible

Some tools are cheap.

Some tools are expensive.

Some tools are fast.

Some tools should not be called repeatedly without a reason.

Agents need that information. Otherwise they may create loops that are technically correct but operationally wasteful.

A good tool description should make cost and latency visible when they matter.

A good tool response should make clear whether the result is complete, partial, cached, stale, or expensive to reproduce.

Without those signals, the agent cannot reason well about trade-offs.

Tool design is workflow design

The best tools are not just technically callable. They fit the workflow.

For code work, that may mean tools that support:

• inspecting relevant files;
• applying small patches;
• running focused tests;
• reporting changed files;
• summarizing assumptions;
• stopping before risky operations.

For research work, it may mean tools that separate search, source reading, extraction, and synthesis.

For product work, it may mean tools that preserve decisions and open questions.

The tool is part of the process. If the process is unclear, the tool cannot compensate.

The principle

A badly designed tool does not just fail.

It teaches the agent the wrong way to work.

That is why agent tooling should be designed with the same care as product interfaces: clear affordances, narrow scope, useful feedback, explicit constraints, and recoverable errors.

A function call is an implementation detail.

The real product is the agent's working environment.