@mastra/core/dist/docs/references/reference-tools-task-tools.md

> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Task tools

Four built-in, agent-agnostic tools that manage a structured task list for an agent run. The task list is persisted in the thread-scoped `threadState` storage domain and projected onto the agent [state-signal](https://mastra.ai/docs/long-running-agents/signals) lane so it survives [observational-memory](https://mastra.ai/docs/memory/observational-memory) truncation.

Task tracking requires a memory-backed thread (`threadId` + `resourceId`). Without memory the tools return an error explaining that task tracking requires agent memory.

The recommended setup is [`TaskSignalProvider`](https://mastra.ai/reference/signals/task-signal-provider), which bundles all four tools and the `TaskStateProcessor` in a single registration. See [Built-in tools](https://mastra.ai/docs/agents/using-tools) for the conceptual guide.

## Usage example

```typescript
import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { TaskSignalProvider } from '@mastra/core/signals'

const agent = new Agent({
  id: 'coder',
  name: 'Coder',
  instructions: 'Track your progress with the task tools.',
  model,
  memory: new Memory(),
  signals: [new TaskSignalProvider()],
})
```

Or import the tools directly:

```typescript
import { taskWriteTool, taskUpdateTool, taskCompleteTool, taskCheckTool } from '@mastra/core/tools'

const agent = new Agent({
  id: 'coder',
  name: 'Coder',
  instructions: 'Track your progress with the task tools.',
  model,
  memory: new Memory(),
  tools: { taskWriteTool, taskUpdateTool, taskCompleteTool, taskCheckTool },
})
```

## `task_write`

Create or replace the entire task list. Each call replaces the previous list.

### Input schema

**tasks** (`TaskItemInput[]`): The complete updated task list.

**tasks.id** (`string`): Stable task identifier (e.g. 'task\_investigate\_tests'). Keep this unchanged across updates. Auto-generated when omitted.

**tasks.content** (`string`): Task description in imperative form (e.g. 'Fix authentication bug').

**tasks.status** (`'pending' | 'in_progress' | 'completed'`): Current task status.

**tasks.activeForm** (`string`): Present continuous form shown during execution (e.g. 'Fixing authentication bug').

### Output

Returns a `TaskToolResult` with a human-readable `content` summary, the full `tasks` array with assigned IDs, and an `isError` flag.

### Behavior

- IDs must be unique within a call. Duplicate explicit IDs get a generated fallback.
- When an ID is omitted while rewriting an existing list, one unambiguous matching task reuses its previous ID for stability.
- Only one task can have `in_progress` status at a time. Submitting multiple `in_progress` tasks returns an error.

## `task_update`

Update one task by its stable ID. Include only the fields that changed.

### Input schema

**id** (`string`): The stable task identifier to update.

**content** (`string`): New task description in imperative form.

**status** (`'pending' | 'in_progress' | 'completed'`): New task status.

**activeForm** (`string`): New present continuous form.

At least one of `content`, `status`, or `activeForm` is required.

### Behavior

- When the update sets a task to `in_progress`, any other `in_progress` task is automatically demoted to `pending`.
- Returns an error with available task IDs when the ID is not found.

## `task_complete`

Mark one task completed by its stable ID.

### Input schema

**id** (`string`): The stable task identifier to mark completed.

### Behavior

Returns an error with available task IDs when the ID is not found.

## `task_check`

Check the completion status of the task list. Takes no input parameters.

### Output

Returns a `TaskCheckResult` with:

**content** (`string`): Human-readable summary with task counts and incomplete task IDs.

**tasks** (`TaskItem[]`): Full task list snapshot with stable IDs.

**summary** (`TaskCheckSummary`): Structured counts.

**summary.total** (`number`): Total tracked tasks.

**summary.completed** (`number`): Completed tasks.

**summary.inProgress** (`number`): In-progress tasks.

**summary.pending** (`number`): Pending tasks.

**summary.incomplete** (`number`): Tasks not yet completed (in-progress + pending).

**summary.hasTasks** (`boolean`): True when at least one task exists.

**summary.allCompleted** (`boolean`): True when at least one task exists and every task is completed.

**incompleteTasks** (`TaskItem[]`): Tasks that still need work (in-progress and pending).

**isError** (`boolean`): Whether the check encountered an error.