AI agent tools: the safe way to give models actions
How to design agent tools with narrow authority, typed inputs, clear descriptions, and observable results.
A tool is not just a helper function
In agent systems, tools are where model output becomes system behavior. A model can ask to call a tool, pass arguments, read the result, and decide what to do next.
That makes tool design a security and product decision. The tool name, description, schema, permissions, and output shape all influence how the agent behaves.
A human user may never see the tool definition, but they feel its quality. A good tool lets the agent answer confidently and recover from errors. A bad tool creates vague failures: the model sends malformed input, receives a confusing error, and guesses its way forward.
Narrow tools beat clever tools
A broad tool feels flexible, but it moves complexity into the model prompt. A narrow tool gives the model fewer ways to be wrong. Compare `update_ticket_status` with a typed status enum to `run_linear_operation` with a free-form operation string.
The narrow version is easier to test, easier to log, and easier to explain to users.
Narrow does not mean tiny. A tool can perform several deterministic steps if those steps always belong together. The key question is whether the model should make a decision between steps. If not, hide the sequence behind a tool. If yes, expose smaller steps and let the agent inspect the result.
Give every tool a reviewable file
Eve tools live in `agent/tools/`, so every callable action has a file. That layout makes review concrete: what can the model ask the system to do, and where is that behavior implemented?
For registry-installed agents, this is especially useful. Users can inspect tool files before giving the agent credentials or connecting a channel.
That does not remove the need for careful schemas. A file path tells you where authority lives. The tool implementation still has to validate inputs, handle errors, redact sensitive output, and make side effects explicit.
What to include in a tool contract
A tool contract should answer five questions: what action does it perform, what input does it accept, what output does it return, what can go wrong, and what side effects can happen. If any of those are unclear, the model and the reviewer are both guessing.
Descriptions should be written for the model, but they should also be readable by humans. Avoid vague verbs like "handle" or "process". Name the action: list, describe, create, update, send, preview, approve.
Decision table
Read tool
Use when
The model needs data from a system, such as schema, issue state, or file content.
Avoid when
The data can be attached as static context or a resource without model-controlled execution.
Write tool
Use when
The agent needs to create, update, send, or trigger something outside itself.
Avoid when
The action is risky and lacks approval, idempotency, or audit logs.
Composite tool
Use when
A sequence is deterministic and should not be controlled step-by-step by the model.
Avoid when
The sequence contains judgment points the model should inspect between steps.
FAQ
Should tools be tiny?
They should be narrow, not necessarily tiny. A tool can do several deterministic steps if the model should not decide between them.
Where should validation happen?
Validate at the tool boundary with schemas and runtime checks. Do not rely on prompt instructions alone.
Should a tool return prose or data?
Return structured data when the agent will reason over it. Use prose only when the output is meant for a human.