Agent Tools Need Product Design Too

A tool can be perfectly designed as an API and still be a bad tool for an agent.

The schema can be valid. The parameters can be typed. The function can return the expected result. The tests can pass.

The agent can still learn the wrong way to work.

That is because an agent does not experience a tool as an isolated operation. It experiences a tool inside a loop: gather context, choose an action, inspect the result, recover from failure, and decide what happens next.

The tool is part of that loop's environment.

Its description tells the agent what is possible. Its parameters shape what can be attempted. Its output determines what can be understood. Its errors influence whether the agent retries, changes direction, or starts guessing.

A tool is therefore not only a capability. It is a control surface.

A successful call can still create a bad loop

The easiest way to evaluate a tool is to ask whether it works.

That is not enough.

A search tool may return results, but bury the useful match in irrelevant output. A migration tool may complete, but provide no evidence of what changed. A test runner may report failure without distinguishing a broken assertion from a missing environment variable.

Every call succeeds technically while the loop becomes harder to reason about.

The failure appears one step later. The agent takes another action using a distorted understanding of the previous result.

This is why tool quality cannot be measured only at the function boundary. The real unit of evaluation is the loop the tool creates around itself.

What context does it require?

What action does it make likely?

What evidence does it return?

What is the recovery path?

When should the agent stop instead of trying again?

Those are product questions, even when the product is used by a model.

Capability is not authority

A tool can expose an operation without owning the decision to perform it.

A repository tool may be capable of editing a file. That does not mean it should decide that the file needs a change.

A deployment tool may be capable of sending an artifact to production. That does not mean a green test result is permission to deploy it.

A memory tool may be capable of storing a statement. That does not mean the statement is approved knowledge.

This distinction matters because agents make capability feel like permission. If an operation is available in the tool list, it appears to belong to the agent's working space.

The boundary has to be designed explicitly.

Some actions can be autonomous because they are reversible, inspectable, and low-risk. Other actions need a decision outside the loop because they change public state, cross a trust boundary, or turn an interpretation into a durable position.

The tool should help express that difference. It should not hide it behind one broad command called run or apply.

Errors are part of the working surface

A human can often recover from a vague error by filling in the missing context from experience.

An agent has less to work with. If the tool says only:

Operation failed.

the next action is left to inference.

A useful error identifies the boundary that stopped the operation, the evidence available so far, and the safe choices that remain.

The migration was not run because DATABASE_URL is missing.
No files were changed. Set DATABASE_URL in an authorized environment, or inspect the generated plan without applying it.

That message does more than report failure. It prevents an unsafe retry, preserves the state of the loop, and makes escalation possible.

The same applies to successful results. A tool should say whether its output is complete, partial, cached, stale, or based on an assumption. An empty result may be valid. A partial result may be more dangerous than an explicit failure.

Feedback is not decoration around the operation. It is how the agent knows what world it is in.

Design the loop, not the function list

Narrow tools are easier to compose, but narrowness alone is not the goal.

The goal is a loop that remains legible when it runs repeatedly.

A useful agent loop normally needs a way to inspect the relevant context, perform a bounded action, observe the result, verify the consequence, and stop before crossing an authority boundary.

A tool that supports only the action is incomplete. A tool that also exposes assumptions, changed files, verification results, cost, and recovery state is part of a more trustworthy working environment.

This does not mean every tool needs a large framework around it. It means the surrounding workflow should make the important distinctions visible.

The agent may be allowed to investigate without approval. It may be allowed to prepare a patch but not apply it. It may be allowed to run a check but not interpret a green result as publication authority.

The capabilities can be close together. The authority cannot be implicit.

The operating rule

The best agent tool does not make the agent autonomous by default.

It makes the next safe action legible. It returns evidence that another step can verify. It distinguishes retry from escalation. It exposes cost and uncertainty when they matter. And it makes clear when the agent has reached a decision that belongs to someone else.

A function call is an implementation detail.

The real product is the loop around it—and the trust boundary that tells the loop where to stop.