# 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 lets the model affect a real system, so every tool needs a narrow job, typed inputs, logs, and clearly declared side effects. Bad tools turn the agent into an unreviewable API gateway where the model has too many ways to surprise you.

## 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

| Choice | Use when | Avoid when |
| --- | --- | --- |
| Read tool | The model needs data from a system, such as schema, issue state, or file content. | The data can be attached as static context or a resource without model-controlled execution. |
| Write tool | The agent needs to create, update, send, or trigger something outside itself. | The action is risky and lacks approval, idempotency, or audit logs. |
| Composite tool | A sequence is deterministic and should not be controlled step-by-step by the model. | The sequence contains judgment points the model should inspect between steps. |

## Examples

### Good tool

`submit_pr_review` accepts a review body and inline comments, then posts one GitHub review with clear rate limits and logging.

### Risky tool

`github_action` accepts any operation and arbitrary JSON. It may demo quickly, but it is difficult to permission or test.

## 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.

---

- Published: 2026-07-01
- Updated: 2026-07-02
- Web page: https://www.evex.sh/learn/ai-agent-tools
- This document: https://www.evex.sh/learn/ai-agent-tools.md
- All guides: https://www.evex.sh/learn