# Playbooks MCP Tools

> The MCP tools the SOAT server exposes for the Playbooks module, with the arguments each tool takes.

# Playbooks

MCP tools for the Playbooks module. See the [Playbooks module docs](/docs/modules/playbooks) for permissions and data model.

### `list-playbooks`

List playbooks

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | no | Project ID (required if not using project key auth) |
| `limit` | `number` | no | Results per page. Above the maximum it is clamped, and `limit` in the response reports the page served; below 1 or not an integer it is `400 VALIDATION_FAILED`. |
| `offset` | `number` | no | Results to skip. Negative or not an integer it is `400 VALIDATION_FAILED`. |

### `create-playbook`

Create a playbook

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | no | Project ID (required if not using project key auth) |
| `name` | `string` | yes | Human-readable name, unique per project |
| `description` | `string \| null` | no | What the playbook is for |
| `definition` | `any` | yes | The nodes and how their inputs are sourced |
| `version_label` | `string` | no | Optional tag for version 1, e.g. `initial` |

### `validate-playbook`

Validate a playbook definition

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `definition` | `any` | yes | The definition to check |

### `get-playbook`

Get a playbook

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `playbook_id` | `string` | yes | The playbook ID |

### `update-playbook`

Update a playbook

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `playbook_id` | `string` | yes | The playbook ID |
| `name` | `string` | no | Human-readable name, unique per project |
| `description` | `string \| null` | no | What the playbook is for |
| `definition` | `any` | no | Replaces the whole definition; a change archives a new version |
| `version_label` | `string` | no | Optional tag for the version this write archives. Ignored when the write changes no definition, since no version is archived. |
| `expected_version` | `any` | no | Refuses the write unless the playbook is at this version. |

### `delete-playbook`

Delete a playbook

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `playbook_id` | `string` | yes | The playbook ID |

### `list-playbook-versions`

List a playbook's versions

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `playbook_id` | `string` | yes | The playbook ID |
| `limit` | `number` | no | Results per page. Above the maximum it is clamped, and `limit` in the response reports the page served; below 1 or not an integer it is `400 VALIDATION_FAILED`. |
| `offset` | `number` | no | Results to skip. Negative or not an integer it is `400 VALIDATION_FAILED`. |

### `get-playbook-version`

Fetch an archived playbook version

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `playbook_id` | `string` | yes | The playbook ID |
| `version` | `number` | yes | The archived version number |

### `restore-playbook-version`

Restore an archived playbook version

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `playbook_id` | `string` | yes | The playbook ID |
| `version` | `number` | yes | The archived version number |
| `label` | `string` | no | Optional tag for the new version. Defaults to `restored from vN`. |

### `create-playbook-case`

Create a case

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `playbook_id` | `string` | yes | The playbook ID |
| `subject` | `string` | yes | Who or what the case is about, as you name it |

### `list-playbook-cases`

List playbook cases

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | no | Project ID (required if not using project key auth) |
| `playbook_id` | `string` | no | Only the cases of this playbook |
| `automation_status` | `array<string>` | no | Only the cases in these automation statuses. Repeat the parameter to OR values. A value outside the enum, empty string included, is a `400`. |
| `limit` | `number` | no | Results per page. Above the maximum it is clamped, and `limit` in the response reports the page served; below 1 or not an integer it is `400 VALIDATION_FAILED`. |
| `offset` | `number` | no | Results to skip. Negative or not an integer it is `400 VALIDATION_FAILED`. |

### `get-playbook-case`

Get a case

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `case_id` | `string` | yes | The case ID |

### `delete-playbook-case`

Delete a case

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `case_id` | `string` | yes | The case ID |

### `write-playbook-case-inputs`

Write a case's inputs

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `case_id` | `string` | yes | The case ID |
| `inputs` | `array<object>` | yes | The writes, applied all or none |
| `wait` | `boolean` | no | Answer once every execution the write queued, and every one those queue in turn, has settled or parked, instead of right away |

### `get-playbook-case-missing`

List what a node still needs

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `case_id` | `string` | yes | The case ID |
| `node_id` | `string` | yes | The ID of the node to reach, usually a final node |

### `list-playbook-case-entries`

List a case's entries

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `case_id` | `string` | yes | The case ID |
| `node_id` | `string` | no | Only the entries of this node |
| `limit` | `number` | no | Results per page. Above the maximum it is clamped, and `limit` in the response reports the page served; below 1 or not an integer it is `400 VALIDATION_FAILED`. |
| `offset` | `number` | no | Results to skip. Negative or not an integer it is `400 VALIDATION_FAILED`. |

### `run-playbook-case-node`

Run a node of a case

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `case_id` | `string` | yes | The case ID |
| `node` | `string` | yes | The ID of a node of the case's playbook version |
| `wait` | `boolean` | no | Answer once the executor settles or parks instead of right away |

### `list-playbook-case-executions`

List a case's executions

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `case_id` | `string` | yes | The case ID |
| `node_id` | `string` | no | Only the executions of this node |
| `limit` | `number` | no | Results per page. Above the maximum it is clamped, and `limit` in the response reports the page served; below 1 or not an integer it is `400 VALIDATION_FAILED`. |
| `offset` | `number` | no | Results to skip. Negative or not an integer it is `400 VALIDATION_FAILED`. |

### `get-playbook-case-execution`

Get an execution

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `case_id` | `string` | yes | The case ID |
| `execution_id` | `string` | yes | The execution ID |

### `export-playbook-case-node`

Export a final node

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `case_id` | `string` | yes | The case ID |
| `node` | `string` | yes | The ID of a node of the case's playbook version |
| `transformations` | `array<string>` | no | The names of the transformations to render; every one the node declares when omitted |
| `revision` | `number` | no | The output or confirmation of the node to render; its current output when omitted |

### `list-playbook-case-exports`

List a case's exports

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `case_id` | `string` | yes | The case ID |
| `node_id` | `string` | no | Only the exports of this node |
| `transformation` | `string` | no | Only the exports of this transformation |
| `limit` | `number` | no | Results per page. Above the maximum it is clamped, and `limit` in the response reports the page served; below 1 or not an integer it is `400 VALIDATION_FAILED`. |
| `offset` | `number` | no | Results to skip. Negative or not an integer it is `400 VALIDATION_FAILED`. |

### `get-playbook-case-export`

Get an export

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `case_id` | `string` | yes | The case ID |
| `export_id` | `string` | yes | The export ID |

### `upgrade-playbook-case`

Upgrade a case

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `case_id` | `string` | yes | The case ID |
| `version` | `number` | no | The version to move the case to; the playbook's current one when omitted |
| `wait` | `boolean` | no | Answer once every execution the write queued, and every one those queue in turn, has settled or parked, instead of right away |

### `list-playbook-case-upgrades`

List a case's upgrades

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `case_id` | `string` | yes | The case ID |
| `limit` | `number` | no | Results per page. Above the maximum it is clamped, and `limit` in the response reports the page served; below 1 or not an integer it is `400 VALIDATION_FAILED`. |
| `offset` | `number` | no | Results to skip. Negative or not an integer it is `400 VALIDATION_FAILED`. |

### `pause-playbook-case`

Pause a case

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `case_id` | `string` | yes | The case ID |

### `resume-playbook-case`

Resume a case

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `case_id` | `string` | yes | The case ID |

### `confirm-playbook-case-node`

Confirm a node of a case

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `case_id` | `string` | yes | The case ID |
| `node` | `string` | yes | The ID of a node of the case's playbook version |
| `decision` | `string` | yes | Whether the node's inputs, as read, are approved |
| `reason` | `string` | no | Why the inputs were rejected; required on a rejection |
| `expected_revisions` | `object` | yes | Each of the node's inputs, by name, mapped to the revision read, or null for one read as unset |
| `wait` | `boolean` | no | Answer once every execution the write queued, and every one those queue in turn, has settled or parked, instead of right away |