> For the complete documentation index, see [llms.txt](https://docs.maetra.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maetra.io/mcp-server/tools-reference.md).

# Tools reference

The Maetra MCP server exposes seven tools. Invoke one with `tools/call`, passing the tool `name` and an `arguments` object:

```json
{
  "jsonrpc": "2.0", "id": 10, "method": "tools/call",
  "params": { "name": "check_action", "arguments": { "content": "…" } }
}
```

***

### check\_action

Scan an AI-agent **prompt, tool call, or output** with Maetra Secure. Backs [`POST /v1/secure/scan`](/secure-api/scanning-content.md). Pass `agent_name` when `agent_id` isn't available.

| Argument     | Type   | Required         | Description                                      |
| ------------ | ------ | ---------------- | ------------------------------------------------ |
| `content`    | string | ✓                | The prompt, tool payload, or output to scan.     |
| `scan_type`  | string |                  | `prompt_input` (default), `tool_call`, `output`. |
| `tool_name`  | string | ✓ if `tool_call` | The tool being called.                           |
| `agent_id`   | string |                  | Registered agent identifier.                     |
| `agent_name` | string |                  | Human-readable agent/product name.               |
| `context`    | object |                  | Structured context.                              |

Returns the scan verdict — see [Scanning content](/secure-api/scanning-content.md).

***

### list\_active\_rules

List the active Maetra Secure rules for the workspace. Backs [`GET /v1/secure/rules`](/secure-api/rules.md). No arguments.

***

### create\_rule

Create a new Secure rule. Backs [`POST /v1/secure/rules`](/secure-api/rules.md). New rules default to `status: draft` — set `status: active` to enforce immediately.

| Argument                                                                                                                      | Type      | Required | Description                                                  |
| ----------------------------------------------------------------------------------------------------------------------------- | --------- | -------- | ------------------------------------------------------------ |
| `name`                                                                                                                        | string    | ✓        | Rule name.                                                   |
| `type`                                                                                                                        | string    | ✓        | `data_pattern`, `policy_dsl`, `prompt_pattern`, `tool_call`. |
| `action`                                                                                                                      | string    |          | `block`, `flag` (default), `log`.                            |
| `severity`                                                                                                                    | string    |          | `critical`, `high`, `medium` (default), `low`.               |
| `status`                                                                                                                      | string    |          | `active`, `archived`, `draft` (default).                     |
| `applies_to_all`                                                                                                              | boolean   |          | Apply to every agent. Defaults to `true`.                    |
| `data_direction`                                                                                                              | string    |          | `inbound`, `outbound`, `both`.                               |
| `custom_patterns`, `tool_names`, `data_categories`, `data_descriptions`, `dsl_statements`, `pattern_library_ids`, `agent_ids` | string\[] |          | Same as the [REST body](/secure-api/rules.md).               |

Returns the created rule.

***

### update\_rule

Update an existing Secure rule by id (get ids from `list_active_rules`). Backs [`PATCH /v1/secure/rules/{id}`](/secure-api/rules.md). Only the fields you pass change.

| Argument                   | Type   | Required | Description                                                                                |
| -------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `id`                       | string | ✓        | The rule ID to update.                                                                     |
| *(any create\_rule field)* |        |          | Sent fields are updated; omitted fields are untouched. List fields are replaced when sent. |

```json
{ "name": "update_rule", "arguments": { "id": "rule_9f2", "status": "active" } }
```

***

### request\_approval

Request human approval before a sensitive action. Backs [`POST /v1/checkpoints`](/govern-api/checkpoints.md). Returns **immediately** with the checkpoint status and ID — if `pending`, keep polling with [`get_approval_status`](#get_approval_status).

| Argument                          | Type      | Required | Description                              |
| --------------------------------- | --------- | -------- | ---------------------------------------- |
| `action`                          | string    | ✓        | The action name, e.g. `transfer_funds`.  |
| `payload`                         | object    |          | Structured details of the action.        |
| `agent_id`                        | string    |          | Registered agent identifier.             |
| `agent_name`                      | string    |          | Human-readable caller name.              |
| `context`                         | string    |          | Free-text context for reviewers.         |
| `reasoning`                       | string    |          | The agent's reasoning.                   |
| `autonomy_level`                  | string    |          | Autonomy level, `L0`–`L5`.               |
| `policy_ids` / `policy_group_ids` | string\[] |          | Restrict evaluation.                     |
| `timeout_seconds`                 | number    |          | Wall-clock ceiling for a human decision. |

Returns a [checkpoint decision](/govern-api/checkpoints.md).

***

### get\_approval\_status

Get the current status of a checkpoint. Backs [`GET /v1/checkpoints/{id}/wait`](/govern-api/checkpoints.md). **Long-polls up to 20 seconds by default**, returning as soon as the state changes.

| Argument        | Type   | Required | Description                                      |
| --------------- | ------ | -------- | ------------------------------------------------ |
| `checkpoint_id` | string | ✓        | The ID returned by `request_approval`.           |
| `wait_seconds`  | number |          | Long-poll hold time, `1`–`55`. Defaults to `20`. |

Call repeatedly until `status` is terminal (`approved`, `rejected`, `expired`, `blocked`, `cancelled`).

***

### list\_active\_policies

List the active Maetra Govern policies for the workspace. Backs [`GET /v1/policies/active`](/govern-api/policies.md). No arguments.