Skip to main content

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.

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: 
{
  "success": true,
  "data": { },
  "error": null
}
A failed response looks like this: 
{
  "success": false,
  "data": null,
  "error": "Description of what went wrong"
}
The three top-level fields are always present:
FieldTypeDescription
successbooleantrue when the ability executed without error, false otherwise
dataobject or nullThe ability’s output on success; null or a diagnostic object on failure
errorstring or nullA human-readable error description on failure; null on success
Never retry a failed ability blindly. Read the error field, understand what went wrong, and fix the input or conditions before trying again.

​
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: 
{
  "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:
FieldDescription
contentThe full rule body
delivery_modeEither inline_on_success or reject_first — describes how this rule was delivered
versionThe 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.
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.

​
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.
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-*.
{
  "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
    }
  }
}
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.
{
  "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
    }
  }
}

​
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.
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 for more detail.