# Operate-layer tool shape

One tool per feature, named `<app>_<feature>` or just `<feature>`. The agent uses it to do what a person does on the feature's screens, through the same use case. If your product already has one such tool, read it before you write the arguments model, and match its shape. Do not invent a second shape.

## Shape

```text
<feature>(command=<verb>, resource=<thing>, ...filters)

verbs, in the order the agent should reach for them:
  overview   the aggregate the product already computes; one call
  list       many rows, filtered, bounded by limit
  get        one row in full
  <mutation> one verb per guarded write: decide, log, update, toggle, create
```

- `command` is a closed enum (`Literal[...]`) in a typed arguments model. Never accept free text for it.
- `resource` is a closed enum when the feature has more than one thing to act on.
- `overview` returns the number the screen shows, computed by the same backend service. The description says so and tells the model not to recompute it by walking rows. A number recomputed from rows drifts from the screen because of sample floors, time windows, and attribution rules the model cannot see.
- Every Surface verb maps to one command. A button that opens a form maps to the mutation the form submits, with the form's fields as arguments.
- Every `get` and `list` row carries `url`, the link to the screen (`/incidents/<id>`), so a result read in chat or Slack opens the screen.
- Reads are free. A mutation carries the same permission check and approval meaning as the same action on the screen.
- Errors are prompts to the model, not to a person: a named code, the input context kept, a list of concrete next actions, and credentials removed.

## Description template

```text
<Verb> <feature> data.

WHAT: one tool over the <feature> feature - <the two or three things it covers>.
<read-only, or which commands change data>.

HOW: pick a command (the verb), then name the resource it acts on:
  <feature>(command=<verb>, resource=<thing>, ...)

Commands:
- overview: ... One call. resource=...
- list: ... resource=...
- get: ...
- <mutation>: ...

Prefer overview before list. Do NOT ...

Typical flow: overview -> list -> get -> <mutation>.

Examples:
- <feature>(command="overview")
- <feature>(command="list", <filter>=..., limit=10)
- <feature>(command="get", <id>="...")
```

## Error template

```text
INCIDENT_NOT_FOUND: no incident with id "inc_42" in this workspace
Context: command=get, id=inc_42
NEXT_ACTIONS (do NOT ask the user):
- incidents(command="list", status="open", limit=10) to find the id
- incidents(command="get", id=<id from the list>)
```

Never write "please try again or contact support". It addresses a person, and the model reads it as "stop".

## What is not an Operate tool

- A wrapper over `read`, `write`, `edit`, `grep`, or `glob` for ordinary files. The agent already has a computer.
- A `save_<state>` and `load_<state>` pair. That is a memory file ([primitives.md](primitives.md)).
- A tool per button. Buttons are verbs on one tool.
- A tool that returns context the model should always have. That is a context block.
- A second tool for a fact that another tool already answers. One capability has one authority.

## Where the use case lives

The use case the tool calls is the one the screen's route calls. The route and the tool are two thin callers. If the logic lives in the route handler, move it into a use case first, then call it from both.
