> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maxicore.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding ability response format and metadata

> Every ability returns the same JSON envelope. Learn the success and error shapes, the _meta fields, and how ability rules are delivered inline.

Every ability call — regardless of which group it belongs to or whether it succeeds — returns a response in the same JSON envelope. Understanding this format lets you write reliable agent logic that handles both successful results and failures consistently.

## Standard envelope

A successful response looks like this:

```json theme={null}
{
  "success": true,
  "data": { },
  "error": null
}
```

A failed response looks like this:

```json theme={null}
{
  "success": false,
  "data": null,
  "error": "Description of what went wrong"
}
```

The three top-level fields are always present:

| Field     | Type           | Description                                                               |
| --------- | -------------- | ------------------------------------------------------------------------- |
| `success` | boolean        | `true` when the ability executed without error, `false` otherwise         |
| `data`    | object or null | The ability's output on success; `null` or a diagnostic object on failure |
| `error`   | string or null | A human-readable error description on failure; `null` on success          |

<Warning>
  Never retry a failed ability blindly. Read the `error` field, understand what went wrong, and fix the input or conditions before trying again.
</Warning>

## The `_meta` envelope

Many responses include a `_meta` object alongside `success`, `data`, and `error`. It carries session-level metadata that your agent needs to track across calls:

```json theme={null}
{
  "success": true,
  "data": { },
  "error": null,
  "_meta": {
    "_rule": { },
    "operator_notes_revision": 4,
    "knowledge_notes_revision": 2
  }
}
```

### `_meta._rule`

When an ability has an associated rule and this is its first call in the session, the rule body is delivered here. The rule tells you the constraints and required patterns for that ability. Read it before acting further on that ability, then retain it for the rest of the session — it is not re-delivered on subsequent calls.

The rule object includes:

| Field           | Description                                                                          |
| --------------- | ------------------------------------------------------------------------------------ |
| `content`       | The full rule body                                                                   |
| `delivery_mode` | Either `inline_on_success` or `reject_first` — describes how this rule was delivered |
| `version`       | The rule's current version; bumps when an operator edits it                          |

### `_meta.operator_notes_revision`

A counter that increments whenever an operator creates or updates an active operator note. At session start, record the value from `bootstrap-session`. If any later response shows a higher value, fetch fresh operator notes with `maxi/list-notes` (filtering by `type=operator-note, status=active`) before your next call and apply the updated instructions.

### `_meta.knowledge_notes_revision`

The same pattern, but for agent-knowledge notes. If this value rises above your baseline, refresh your knowledge-note headers by calling `maxi/list-notes` with `type=agent-knowledge, status=active` before your next call.

<Note>
  Both revision counters are soft signals — the in-flight request that delivered the change is not blocked. You act on the refresh before your next tool call, not immediately.
</Note>

## Ability rules delivery modes

Rules control whether an ability runs immediately or requires the agent to read and acknowledge constraints first. The mode is fixed per ability type.

<AccordionGroup>
  <Accordion title="inline_on_success — read-only abilities">
    The ability executes on the first call. The rule body is attached to the successful response under `_meta._rule`, and the session marks the rule as acknowledged. On all later calls in the same session, the rule is not re-attached — the ability just runs.

    This mode is used for all read-only abilities: `get-*`, `list-*`, and `search-*`.

    ```json theme={null}
    {
      "success": true,
      "data": { },
      "error": null,
      "_meta": {
        "_rule": {
          "content": "Read the returned content carefully before passing it to the user.",
          "delivery_mode": "inline_on_success",
          "version": 1
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="reject_first — write and mutation abilities">
    The first call is refused with a `rules_not_acknowledged` error, and the rule body is attached to that rejection under `_meta._rule`. Read the rule, then retry the exact same call — the retry is treated as the acknowledgement and the ability runs. The rule body is not re-attached on the retry or on any later call in the same session.

    This mode is used for write and mutation abilities: `create-*`, `update-*`, `delete-*`, `assign-*`, `remove-*`, `set-*`, `bulk-*`, `generate-*`, `upload-*`, `attach-*`, `detach-*`, and similar write-prefixed abilities.

    ```json theme={null}
    {
      "success": false,
      "data": null,
      "error": "rules_not_acknowledged",
      "_meta": {
        "_rule": {
          "content": "Before creating content, always read the existing post first.",
          "delivery_mode": "reject_first",
          "version": 1
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Rule version changes

If an operator edits a rule while a session is active, the rule's `version` value increases. The next call to that ability re-delivers `_meta._rule` according to the rule's current `delivery_mode`. Treat an unexpected `_meta._rule` on a non-first call as a signal that the rule has changed — re-read it and incorporate the updated constraints before continuing.

## Manual rule fetch

You can always fetch a rule explicitly without invoking its ability by calling `maxi/get-ability-rule` with the ability's ID. This is useful if your MCP client doesn't surface the `_meta._rule` body from a `reject_first` rejection, or when you want to inspect a rule in advance. Calling `maxi/get-ability-rule` also marks the rule as acknowledged for the current session, so the ability's first real call passes through without a rejection.

<Tip>
  If you are using Codex or another client that collapses structured error responses into a generic message, call `maxi/get-ability-rule` before your first write ability call. This is the reliable workaround for the `reject_first` gate on clients that cannot surface the rule from the rejection. See [Handling errors](/abilities/error-handling) for more detail.
</Tip>