ActionSchema: Substrate Action Descriptor Reference

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

signature

string

required

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.

reversibility

enum

required

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.

description

string

required

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.

confidence

float

required

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.

parameters

array

required

An ordered list of parameter descriptors for the action. You must supply all required parameters when calling POST /action; optional parameters may be omitted.

Show parameter object fields

name

string

required

The parameter name as it appears in the signature string and as you must supply it in the parameters object of an ActionRequest.

type_name

string

required

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"]`

required

boolean

required

true if you must include this parameter in the ActionRequest.parameters object. Omitting a required parameter results in a 400 Bad Request.

description

string | null

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:

{
  "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.

Endpoints

Data Models

Full JSON Example

Reversibility and Action Gating

​Full JSON Example

​Reversibility and Action Gating

Full JSON Example

Reversibility and Action Gating