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
Section titled “Effect”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
Section titled “Approval”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
Section titled “Surfaces”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.
Results: open and redact
Section titled “Results: open and redact”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.
Guards
Section titled “Guards”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.
Deferred operations
Section titled “Deferred operations”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 spelling
Section titled “CLI spelling”cli sets the command words and positional arguments:
{ "name": "stop_vm", "cli": { "command": "vm stop", "args": ["vm_id"] } }aidy vm stop vm-42 --forcedWithout it, the command is the name with - (stop-vm) and every argument is a flag. See the
CLI guide.