# Tasks

> MCP tools for the Tasks module. See the [Tasks module docs](/docs/modules/workflows) for permissions and data model.

# Tasks

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

### `list-tasks`

List tasks

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | no | — |
| `workflow_id` | `string` | no | — |
| `state` | `string` | no | — |
| `status` | `string` | no | — |
| `automation_status` | `array<string>` | no | Filter by the current state's dispatch status. Repeat the parameter to OR values. `none` selects the tasks whose `automation_status` is `null` — the ones that never entered a state with an automation. It is a value a task really holds, so it is a value of the filter too; the parameter's own absence already means "every task". A value outside the enum, empty string included, is a `400`. |
| `assignee` | `string` | no | — |
| `limit` | `number` | no | Maximum number of results to return |
| `offset` | `number` | no | Number of results to skip |

### `create-task`

Create a task

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `project_id` | `string` | no | — |
| `workflow_id` | `string` | yes | — |
| `title` | `string` | yes | — |
| `payload` | `object` | no | — |
| `assignee` | `string \| null` | no | — |
| `state` | `string` | no | Name of a declared workflow state to create the task in directly, instead of the workflow's `initial` state. Must name a state declared on the workflow, or the request is rejected with `TASK_STATE_NOT_FOUND` (400). Defaults to the `initial` state. |
| `tool_context` | `object` | no | Key-value pairs forwarded as `X-Soat-Context-<key>` headers on every `http`, `mcp` and `builtin` tool call made by this task's automation dispatches — the agent generations a state's `on_enter` starts, and the agent nodes of any orchestration run it starts. The header name is `X-Soat-Context-` plus the key verbatim; no character is re-cased. Creation is the task's first move, so this is the bag the entry state's `on_enter` runs with. Each transition may replace it (see `TransitionTaskRequest.tool_context`). The reserved identity keys (`session_id`, `actor_id`, `actor_external_id`) are stripped in any casing and re-derived server-side, so a task-dispatched generation cannot forge them. A key outside the HTTP header-name grammar is rejected with `INVALID_TOOL_CONTEXT_KEY` (400). Write-only: the stored bag is never returned by any task read, and it is cleared when the task reaches a terminal state. |
| `metadata` | `object` | no | Caller-supplied key/value metadata attached to the task record for attribution — which of your own tenants the task belongs to, the ticket that raised it, the import batch that created it. Round-trips verbatim on every read of the task, the list included, and survives every transition (a transition supplies no metadata of its own). The bag is caller-owned and no key is reserved: everything the engine decides about a task (`state`, `status`, `workflow_version`, `last_result`, `active_dispatch`, the automation fields) is a field of its own and cannot be written from here. Prefer this over `payload` for anything that is not task data: `payload` is read by every guard as `task.payload` and may be written by the workflow's declared `payload_writes`, so a label parked there is neither invisible to the state machine nor safe from it. A non-object is rejected with `400 VALIDATION_FAILED` and no task is created. |

### `get-task`

Get a task

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `task_id` | `string` | yes | — |

### `update-task`

Update a task

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `task_id` | `string` | yes | — |
| `title` | `string` | no | — |
| `payload` | `object` | no | Partial payload, shallow-merged over the existing payload. Omitted keys are preserved; provided keys overwrite. The merged result must satisfy the workflow's payload_schema. |
| `assignee` | `string \| null` | no | — |

### `delete-task`

Delete a task

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `task_id` | `string` | yes | — |

### `transition-task`

Transition a task

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `task_id` | `string` | yes | — |
| `transition` | `string` | yes | — |
| `note` | `string \| null` | no | — |
| `tool_context` | `object` | no | Caller context for the automation dispatches the task makes from here on, forwarded as `X-Soat-Context-<key>` headers on their tool calls. Supplying it **replaces** the task's stored bag wholesale; omitting it keeps the current one, so the context follows whoever last moved the task and survives every move that does not speak about it — including an approval gate, a retry, and an automation hop. Send an empty object to clear it without closing the task. The reserved identity keys (`session_id`, `actor_id`, `actor_external_id`) are stripped in any casing and re-derived server-side. A key outside the HTTP header-name grammar is rejected with `INVALID_TOOL_CONTEXT_KEY` (400). Write-only: never returned by a task read, and cleared when the transition closes the task. |

### `pause-task`

Pause a task

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `task_id` | `string` | yes | — |
| `reason` | `string` | no | Why the task is being paused, surfaced on `pause_reason`. |

### `resume-task`

Resume a task

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `task_id` | `string` | yes | — |

### `get-task-history`

Get task history

#### Arguments

| Argument | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `task_id` | `string` | yes | — |