# Tools reference

The Maetra MCP server exposes a capability-dependent tool set. Call `tools/list` to discover the tools available to the current workspace and API key.

Invoke a tool with `tools/call`:

```json
{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "check_task_alignment",
    "arguments": {
      "mcp_access_token": "<token from get_mcp_access>",
      "session_ref": "conversation_01JY8Q",
      "action": "Edit the refund approval route"
    }
  }
}
```

### Access preflight

#### get\_mcp\_access

Required first call for every new user turn or work cycle, after context compaction or restart, and whenever Maetra requests an access refresh. No arguments.

The response contains:

| Field | Description |
| ----- | ----------- |
| `workspace` | Workspace ID, MCP enabled state, and configuration version. |
| `capabilities` | Enabled state, reason, and allowed tools for Secure, Govern, and Task Guard. |
| `required_behavior` | Runtime instructions the host must follow. |
| `mcp_access_token` | Short-lived token required by every capability tool. |
| `expires_at` | Access-token expiry. |

```json
{
  "name": "get_mcp_access",
  "arguments": {}
}
```

> **Note**
> Every tool below requires an additional string argument, `mcp_access_token`, containing the current token returned by `get_mcp_access`.


### Task Guard tools

#### start\_task

Start or transition to the current user-authorized Task Guard task.

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `session_ref` | string | ✓ | Stable host conversation or session reference. |
| `objective` | string | ✓ | The direct user's current objective. |
| `idempotency_key` | string | ✓ | Stable retry key for the task start. |
| `title` | string | | Short task title. |
| `agent_name` / `agent_id` | string | | Agent identity. |
| `constraints`, `decisions` | string[] | | User constraints and agreed decisions. |
| `success_criteria` | string[] | | Observable completion conditions. |
| `in_scope`, `out_of_scope` | string[] | | Explicit task boundaries. |
| `open_questions` | string[] | | Unresolved questions. |
| `direct_user_event_id` | string | | Required for a later task or contract revision in the same session. |
| `host_type` | string | | `CODEX`, `CLAUDE`, `CUSTOM_MCP`, or `CUSTOM_API`. |
| `integration_mode` | string | | `ADVISORY` or `ENFORCED`. |
| `confirmation_capable` | boolean | | Whether the host can ask the session user inline. |
| `effect_reporting_capable` | boolean | | Whether the host can report actual effects. |

After starting, retain `task.id`, `contract_version`, and the returned anchor.

#### get\_task\_context

Retrieve the active Task Guard contract after turn start, compaction, restart, or when context may be stale.

| Argument | Type | Required |
| -------- | ---- | -------- |
| `session_ref` | string | ✓ |

#### check\_task\_alignment

Check a proposed material action against the active task before executing it.

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `session_ref` | string | ✓ | Stable session reference. |
| `action` | string | ✓ | Concise proposed action. |
| `action_type` | string | | Category such as `edit`, `read`, `send`, `create`, or `execute`. |
| `target` | string | | File, system, person, artifact, or other target. |
| `effects` | string[] | | Expected direct and connected effects. |
| `rationale` | string | | Why the action supports the task. |
| `current_step` | string | | Current task step. |
| `contract_version` | number | | Last contract version fetched by the host. |
| `external_action_id` | string | | Stable host action ID used to bind effect reporting. |
| `idempotency_key` | string | | Stable retry key. |
| `effect` | string | | `READ`, `SEARCH`, `CREATE`, `MODIFY`, `DELETE`, `COMMUNICATE`, `PUBLISH`, `EXECUTE`, `PURCHASE`, `TRANSFER`, `GRANT_ACCESS`, `REVOKE_ACCESS`, `MOVE_DATA`, `SCHEDULE`, or `OTHER`. |
| `tool_name`, `operation` | string | | Tool and operation being checked. |
| `resource`, `destination` | object | | Structured target and destination metadata. |
| `data_classes` | string[] | | Data classifications involved. |
| `reversible` | boolean | | Whether the action can be undone. |
| `estimated_cost` | number | | Estimated monetary cost. |
| `provenance` | string | | `HOST_VERIFIED`, `TOOL_ADAPTER_VERIFIED`, `CONNECTOR_VERIFIED`, `AGENT_ASSERTED`, or `UNVERIFIED`. |
| `claimed_relationship` | string | | How the action supports the task: `DIRECT`, `REQUIRED_DEPENDENCY`, `COMPATIBILITY_REPAIR`, `VERIFICATION`, `SUPPORTING_RESEARCH`, `SUPPORTING_COORDINATION`, `INCIDENTAL_CLEANUP`, `OPTIONAL_IMPROVEMENT`, `OBJECTIVE_CHANGE`, `UNRELATED`, or `UNKNOWN`. |

Follow the returned `verdict` and `next_action` exactly. See [Alignment verdicts](https://maetra.io/docs/task-guard-api/alignment-and-effects#verdicts-and-required-behaviour).

#### explain\_task\_relationship

Provide bounded evidence when `check_task_alignment` returns `NEEDS_EXPLANATION`.

| Argument | Type | Required |
| -------- | ---- | -------- |
| `check_id` | string | ✓ |
| `relationship` | string | ✓ |
| `evidence` | string[] | |

The response is a new alignment decision. Follow its verdict.

#### record\_task\_progress

Record a compact milestone for the active task.

| Argument | Type | Required |
| -------- | ---- | -------- |
| `session_ref` | string | ✓ |
| `summary` | string | ✓ |
| `idempotency_key` | string | ✓ |
| `completed`, `next_steps` | string[] | |
| `new_dependencies`, `open_questions` | string[] | |
| `current_step` | string | |

Check every `new_dependencies` item with `check_task_alignment` before acting on it.

#### record\_action\_effect

Report what a previously checked action actually changed.

| Argument | Type | Required |
| -------- | ---- | -------- |
| `check_id` | string | ✓ |
| `actual_effects` | string[] | ✓ |
| `actual_effect` | string | |
| `affected_resources` | object[] | |
| `result_reference`, `artifact_hash` | string | |
| `summary`, `validation_outcome` | string | |

If `effect_aligned` is false, stop expanding the work and ask the session user inline.

#### complete\_task

Complete the active Task Guard task when the objective and success criteria are satisfied.

| Argument | Type | Required |
| -------- | ---- | -------- |
| `session_ref` | string | ✓ |
| `summary` | string | ✓ |
| `completion_event_id` | string | ✓ |

### Secure tools

#### check\_action

Scan an AI-agent prompt, tool call, or output with Maetra Secure. Backs [`POST /v1/secure/scan`](https://maetra.io/docs/secure-api/scanning-content).

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `content` | string | ✓ | Prompt, tool payload, or output to scan. |
| `scan_type` | string | | `prompt_input` (default), `tool_call`, or `output`. |
| `tool_name` | string | ✓ if `tool_call` | Tool being called. |
| `agent_id`, `agent_name` | string | | Agent identity. |
| `context` | object | | Structured context. |

Honor `safe`, `flagged`, or `blocked` before continuing.

#### list\_active\_rules

List active Secure rules. No arguments beyond `mcp_access_token`.

#### create\_rule

Create a Secure rule. New rules default to `draft`.

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `name` | string | ✓ | Rule name. |
| `type` | string | ✓ | `data_pattern`, `policy_dsl`, `prompt_pattern`, or `tool_call`. |
| `action` | string | | `block`, `flag`, or `log`. |
| `severity` | string | | `critical`, `high`, `medium`, or `low`. |
| `status` | string | | `active`, `archived`, or `draft`. |
| `applies_to_all` | boolean | | Defaults to `true`. |
| `data_direction` | string | | `inbound`, `outbound`, or `both`. |
| `custom_patterns`, `tool_names`, `data_categories`, `data_descriptions`, `dsl_statements`, `pattern_library_ids`, `agent_ids` | string[] | | Rule-specific values. |

#### update\_rule

Update an existing Secure rule by ID. `id` is required; every create-rule field is optional and only submitted fields change.

### Govern tools

#### request\_approval

Request a Govern checkpoint before a consequential action. Backs [`POST /v1/checkpoints`](https://maetra.io/docs/govern-api/checkpoints).

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `action` | string | ✓ | Action name. |
| `payload` | object | | Structured action details. |
| `agent_id`, `agent_name` | string | | Agent identity. |
| `context`, `reasoning` | string | | Reviewer context and agent reasoning. |
| `autonomy_level` | string | | `L0`–`L5`. |
| `policy_ids`, `policy_group_ids` | string[] | | Restrict evaluation. |
| `timeout_seconds` | number | | Wall-clock ceiling for a human decision. |
| `idempotency_key` | string | | Stable retry key for creating the checkpoint. |
| `target` | object | | Exact account, resource, destination, or external system. Required for execution authorization. |
| `task_authorization` | object | | Task authority containing `task_id`, `revision_id`, and `external_action_id`. Required for execution authorization. |
| `runtime` | object | | Versioned tool or model identity. Required for execution authorization. |
| `executor_audience` | string | | Intended executor identity. Defaults to `maetra-executor`. |

If the response is `pending`, continue polling with `get_approval_status`. An approved response is the decision; call `authorize_execution` immediately before the external action to consume that approval once.

An approved response includes the signed `decisionToken`, canonical `actionEnvelope`, `actionEnvelopeHash`, `policyDigest`, exact `policyVersions`, token lifecycle timestamps, and the expected execution and effect deadlines. Maetra carries these fields into the MCP execution tools automatically when you provide the checkpoint ID.

#### get\_approval\_status

Long-poll a Govern checkpoint.

| Argument | Type | Required |
| -------- | ---- | -------- |
| `checkpoint_id` | string | ✓ |
| `wait_seconds` | number | |

Poll until `approved`, `rejected`, `expired`, `blocked`, or `cancelled`.

#### list\_active\_policies

List active Govern policies, including whether each uses exact rules or decision intelligence. No arguments beyond `mcp_access_token`.

#### authorize\_execution

Consume an approved decision capability once, immediately before the exact provider request. Maetra reloads the checkpoint, verifies its signed decision and canonical action envelope, and creates a signed execution receipt.

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `checkpoint_id` | string | ✓ | Approved checkpoint returned by `request_approval`. |
| `idempotency_key` | string | ✓ | Stable key for this exact execution. An identical retry returns the existing authorization. |
| `provider` | string | ✓ | External provider or system receiving the request. |
| `operation` | string | ✓ | Provider operation, such as `refunds.create`. |
| `request` | JSON | ✓ | Normalized downstream request that will be sent after authorization. |

Do not call the provider first. A changed request, wrong executor, expired or revoked decision, or second independent use fails. Provider retries remain possible under the returned `executionId`.

#### record\_execution\_attempt

Append one immutable provider attempt to the authorized execution. Record successes, failures, timeouts, and retries against the same `execution_id`.

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `execution_id` | string | ✓ | ID returned by `authorize_execution`. |
| `attempt_number` | number | ✓ | Positive attempt sequence, starting at `1`. |
| `request` | JSON | ✓ | Request sent for this provider attempt. |
| `response` | JSON | | Provider response, when available. |
| `status` | string | ✓ | `succeeded`, `failed`, or `unknown`. |
| `started_at` | string | ✓ | ISO 8601 provider-start time. |
| `completed_at` | string | | ISO 8601 completion time, when known. |
| `provider_status`, `provider_transaction_id`, `error_class` | string | | Provider reconciliation details. |

A failed or unknown attempt does not consume another decision. Retry only the identical authorized action, then record the next attempt number.

#### record\_execution\_effect

Append the state observed after execution. This connects the approved action and provider attempt to what actually changed.

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `execution_id` | string | ✓ | Authorized execution being verified. |
| `observation` | JSON | ✓ | External state observed after execution. |
| `observed_at` | string | ✓ | ISO 8601 observation time. |
| `verification_method` | string | ✓ | `provider_signed`, `ledger_readback`, `hardware_attested`, `stake_backed`, `task_guard`, or `self_reported`. |
| `verification_status` | string | | `verified`, `mismatch`, or `unverified`; defaults to `unverified`. |
| `proof` | JSON | | Method-specific proof. |
| `provider`, `external_reference`, `task_guard_effect_report_id` | string | | Reconciliation links. |

Self-reported observations remain labelled `unverified`. Independent verification methods require their configured verifier to validate the proof; the caller cannot turn an unverified observation into a verified receipt by setting a boolean.

### Ordering multiple controls

For the same material action:

1. Call `check_task_alignment` when Task Guard is enabled.
2. Call `check_action` before processing untrusted content or executing the tool call.
3. Call `request_approval` before the external action when Govern is enabled.
4. Poll until the decision is terminal; stop unless it is approved.
5. Call `authorize_execution` immediately before the exact provider request.
6. Execute only after authorization succeeds, then call `record_execution_attempt` for every provider attempt.
7. Call `record_execution_effect` with the resulting observed state.
8. Call `record_action_effect` when Task Guard effect reporting is enabled.

Task Guard inline confirmation does not replace Govern approval, and Govern approval does not replace one-use execution authorization.