Skip to content

Operations and effects

Each catalog operation says what it does (effect), whether the user confirms it (approval), and where it appears (surfaces). aidy derives sensible defaults from the HTTP method, so most operations only need name and description.

effect Meaning Default for
read Reads data, changes nothing. GET, HEAD
create Creates something. POST
update Changes something that exists. PUT, PATCH
delete Removes something. DELETE
external Reaches outside the product: sends mail, charges a card. none

Set effect whenever the method does not say what the call does. POST /api/vm/{vm_id}/stop changes an existing server, so it is an update; a POST search endpoint is a read.

{ "name": "stop_vm", "effect": "update" }

Every effect other than read is a write. The effect also sets the MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint) and the effect field of the approval card.

approval Meaning
never The call runs at once. Default for read.
always The user confirms each call. Default for every write.

There is no third option, and no prompt can change it: approval is decided in runtime code from the catalog. A read that should be confirmed, such as exporting a full customer list, can set approval: "always". See Approvals.

surfaces lists where an operation appears: agent, mcp, cli.

Effect Default surfaces
read agent, mcp, cli
any write agent, cli

The MCP server is therefore read-only by default. Listing mcp on a write exposes it to MCP clients, and each call then requires the client to confirm through MCP elicitation; a client without elicitation sees the tool, but its calls are refused with an explanation. The aidy CLI connects over MCP too and also sees operations on the cli surface, asking for confirmation on the terminal.

Role operations (identity, search, form) have no surfaces and are never offered to the model as tools. Search reaches the model through the built-in search tool instead.

open is a product page shown after a successful call. It is a path template filled from the arguments and the result, and must start with /:

{ "name": "stop_vm", "open": "/console/instance/{vm_id}" }

After success, the run emits a CUSTOM event aidy.ui.open with {"path": "/console/instance/vm-42"}, and @aidy-dev/react passes the path to your router.

redact lists result fields removed before the model or an MCP client sees them, at any depth:

{ "name": "get_vm", "redact": ["ip", "root_password_hint"] }

Fields with secret-like names (password, token, api_key, authorization, cookie and similar) are always removed, from results and from the arguments shown in events.

aidy applies these guards to every call within one run, in code:

Situation What happens
The model repeats a write with identical arguments Answered from the first result, without a second approval or call. The tool result carries deduplicated: true. Set repeatable: true to allow identical writes, for example “add one more GPU”.
The model repeats a read that already succeeded Refused with repeated_call; the model must answer from the result it has.
The model retries an approved write that failed Refused with already_attempted; the model must tell the user why it failed.
The arguments do not match the input schema Returned as invalid_arguments; nothing reaches your API.
The model calls several tools and one pauses for the user The rest return not_executed and may be called again after the answer.

timeoutSeconds bounds each call, 120 seconds by default and at most 3600. A call that runs out fails with timeout. A host error answers http_{status}, for example http_403, with the host’s error message and, as detail, its error body (redacted, at most 4 KB), so the model can correct the call from structured fields.

These codes go back to the model, which explains the outcome to the user in its own words.

An operation that takes longer than a request can answer 202 with {"aidyTask": "<id>"}. The run pauses with an aidy:task interrupt until your host completes the task through POST /aidy/v0/tasks/{taskId}, signed with an Aidy-Host-Assertion. See AG-UI profile.

cli sets the command words and positional arguments:

{ "name": "stop_vm", "cli": { "command": "vm stop", "args": ["vm_id"] } }
Terminal window
aidy vm stop vm-42 --forced

Without it, the command is the name with - (stop-vm) and every argument is a flag. See the CLI guide.