Tools Are Part of the Agent's Intelligence

People talk about giving an agent more tools as if they were adding buttons to a control panel. Add Jira. Add Confluence. Add GitHub. Add Postman. Now the agent is more capable.

Sometimes it is. Sometimes you have just built a larger menu of ambiguously named actions and made it harder for the agent to choose correctly.

A tool is not an API wrapper from the agent's point of view. It is a piece of reasoning infrastructure. Its name, description, parameters, return value, permissions, and failure behavior all shape the decisions the agent can make.

A tool is part of an agent's intelligence because it determines what the agent can know and how safely it can act.

The hidden cost of a bad tool

Imagine a tool called update_issue. It accepts an issue ID and a free-form payload. Technically, it can do everything: change the status, assign an owner, move the issue to a sprint, add a comment, or alter an estimate.

It is also asking the agent to reconstruct your entire process from one dangerous verb.

A better interface exposes the meaningful actions separately. Assign the issue. Move it to In Progress. Add it to the current sprint. Set story points. Each action has a narrower purpose and a smaller set of valid inputs. The agent has fewer ways to misunderstand the operation.

This is the same reason good application code uses domain functions instead of one universal mutate function. The boundary carries meaning.

Descriptions are executable design

Humans can fill in missing details from experience. Agents cannot reliably do that, especially when several interpretations are plausible. A tool description should answer the questions an agent will have at the moment of choice:

• What does this action change?
• What does it leave untouched?
• When should it be used?
• What does success look like?
• What happens when the requested state is already true?
• Which actions are forbidden or require confirmation?

A description that says "updates a ticket" is almost empty. A description that says "moves an assigned ticket into the current sprint without changing its estimate" gives the agent an actual contract.

The return value matters just as much. Returning "done" hides the new state. Returning the issue ID, status, assignee, sprint, and a clear error gives the next step something reliable to reason from.

Prefer tools that make wrong actions difficult

The best tools do not merely explain the right behavior. They make common wrong behavior hard to express. This is the poka-yoke idea applied to agent interfaces: shape the tool so a mistake becomes impossible or obvious.

A tool that opens a pull request should not silently choose the base branch. A deployment tool should expose the target environment explicitly. A production mutation should not look identical to a staging mutation with one invisible string changed.

Narrow parameters help. Typed enums help. Read-only previews help. Separate approval actions help even more. The agent should be able to inspect what it is about to do before it commits to the irreversible part.

That is not excessive ceremony. It is how you move risk out of the model's free-form language and into a boundary you can test.

One excellent tool beats five overlapping ones

Tool count is another place where agent design starts to resemble multi-agent design. More looks more capable. In practice, overlapping tools create routing uncertainty. The agent spends tokens deciding which nearly identical action to call, then has to recover when the chosen tool has subtly different semantics.

I would rather expose one clear tool for a meaningful operation than five endpoints that reflect how the backend happens to be organized. The agent does not need to see your internal service decomposition. It needs a stable action model.

This is also where MCP servers can either help or hurt. Connecting Jira, Confluence, docs, and Postman gives an agent access to the world. But access alone is not context. Each server still needs coherent names, useful descriptions, predictable errors, and permissions that match the workflow.

Design tools from the failure backwards

Start with a real mistake. The agent branched from stale main. It guessed a story-point estimate. It used the wrong API endpoint. It opened a pull request without the required context.

Now ask which tool boundary allowed the mistake. Was the information missing? Was the action too broad? Could the tool have returned the state the agent needed? Did the agent have a safe way to ask for confirmation?

Fix the boundary, not just the prompt. A prompt correction helps one context. A better tool helps every future context that reaches the same decision.

The reframe

We usually describe tools as the agent's hands. I think they are closer to its senses and its joints. They determine what it can perceive, which movements are available, and where the force of a bad decision lands.

A strong model with weak tools is a talented engineer working through a broken dashboard. A modest model with clear, narrow, truthful tools can often do much better because the environment removes whole categories of error.

Look at the most important tool your agent uses today. Can it explain its contract? Can it show the state it changed? Can it make a dangerous action explicit? If not, that tool is not finished just because the API call works.

The next boundary is not a tool at all. It is the moment where the agent should stop, surface uncertainty, and let a person decide.