> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nelieo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# ActionSchema: Substrate Action Descriptor Reference
> Reference for the ActionSchema object — the typed signature, reversibility tier, parameters, and confidence for a single discoverable substrate action.
An `ActionSchema` describes a single action that NSP's probe has discovered on a running application. You receive these objects as values inside the `actions` map of a [`SubstrateState`](/models/substrate-state) response, and you can also retrieve the full schema for a given application directly via `GET /schema`. Each schema tells you exactly what arguments the action expects, whether calling it will cause irreversible side effects, and how confident NSP is in the discovered mapping — before you attempt to invoke it.
A human-readable typed function signature string representing the action's calling convention as NSP discovered it. The format follows a lightweight function-notation style:
```
fn(thread_id: string, body: string, cc?: string[]) -> bool
```
A `?` suffix on a parameter name marks it as optional. The return type after `->` reflects the runtime's actual return value. Use this field to understand what types to pass and what to expect back in `result`.
The reversibility tier classifies the action's side-effect profile. NSP enforces this as a **safety contract** — it is not advisory. The tier determines both the minimum `confidence` required on the `SubstrateState` before you can invoke the action, and whether a `verify_expression` is mandatory.
| Value | Meaning | Min confidence | `verify_expression` |
| -------------------- | --------------------- | -------------- | ------------------- |
| `read` | No state change | `0.0+` | Optional |
| `reversible_write` | Undoable change | `0.80+` | Optional |
| `irreversible_write` | Permanent side effect | `0.95+` | **Required** |
For details on how reversibility interacts with request gating, see [Action Safety](/security/action-safety).
A plain-English description of what the action does, generated from the probe's semantic labeling. For example: `"Send a reply to an email thread"` or `"Permanently delete a message — cannot be undone"`. Use this when surfacing available actions to an agent or user.
A per-action quality score from `0.0` to `1.0` representing how certain NSP is that the internal runtime target it discovered actually implements this action correctly. This is distinct from the top-level `SubstrateState.confidence`, which reflects overall probe coverage. An action with `confidence: 0.75` may exist in a state snapshot with `confidence: 0.97` — it means NSP is less certain about that specific action's mapping.
An ordered list of parameter descriptors for the action. You must supply all `required` parameters when calling `POST /action`; optional parameters may be omitted.
The parameter name as it appears in the `signature` string and as you must supply it in the `parameters` object of an [`ActionRequest`](/models/action-request).
The expected value type. One of `string`, `number`, `boolean`, `object`, or `array`.
| Type name | Description | Example |
| --------- | ---------------- | ------------------------ |
| `string` | UTF-8 string | `"msg_18821af3"` |
| `number` | Integer or float | `42`, `3.14` |
| `boolean` | True or false | `true` |
| `object` | JSON object | `{"key": "val"}` |
| `array` | JSON array | `["a@x.com", "b@x.com"]` |
`true` if you must include this parameter in the `ActionRequest.parameters` object. Omitting a required parameter results in a `400 Bad Request`.
Human-readable hint describing what value to pass, often referencing the relevant `objects` key where you can find a suitable value. For example: `"Thread ID from inbox.emails[N].thread_id"`.
***
## Full JSON Example
The following shows an `ActionSchema` for an irreversible send action and a reversible archive action, as they appear inside `SubstrateState.actions`:
```json theme={null}
{
"send_reply": {
"signature": "fn(thread_id: string, body: string, cc?: string[]) -> bool",
"reversibility": "irreversible_write",
"description": "Send a reply to an email thread",
"confidence": 0.99,
"parameters": [
{
"name": "thread_id",
"type_name": "string",
"required": true,
"description": "Thread ID from inbox.emails[N].thread_id"
},
{
"name": "body",
"type_name": "string",
"required": true,
"description": "Reply body text (plain text or HTML)"
},
{
"name": "cc",
"type_name": "array",
"required": false,
"description": "Optional CC email addresses"
}
]
},
"archive": {
"signature": "fn(email_id: string) -> bool",
"reversibility": "reversible_write",
"description": "Archive an email — can be undone via unarchive",
"confidence": 0.98,
"parameters": [
{
"name": "email_id",
"type_name": "string",
"required": true,
"description": "Email ID from inbox.emails[N].id"
}
]
},
"get_thread": {
"signature": "fn(thread_id: string) -> object",
"reversibility": "read",
"description": "Fetch the full message thread without modifying state",
"confidence": 0.99,
"parameters": [
{
"name": "thread_id",
"type_name": "string",
"required": true,
"description": "Thread ID from inbox.emails[N].thread_id"
}
]
}
}
```
***
## Reversibility and Action Gating
The `reversibility` value is the foundation of NSP's safety model. When you attempt to invoke an action, NSP checks the reversibility tier against the current `SubstrateState.confidence` before dispatching:
* **`read`** — No gate. Safe to call even during probe warm-up.
* **`reversible_write`** — Requires `confidence >= 0.80`. NSP rejects the request if confidence is below this threshold.
* **`irreversible_write`** — Requires `confidence >= 0.95` **and** a `verify_expression` in the `ActionRequest`. Submitting an irreversible action without a `verify_expression` raises `NSPIrreversibleNotConfirmedError`.
For a full explanation of how these gates are enforced and how to configure per-action overrides, see [Action Safety](/security/action-safety).