# 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 | | The agent's claimed relationship to the task. |

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

If the response is `pending`, continue polling with `get_approval_status`. Proceed only after `approved`.

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

### 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. Execute only after every enabled control permits it.
5. Call `record_action_effect` after execution when Task Guard effect reporting is enabled.

Task Guard inline confirmation does not replace Govern approval.