> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/jackdog668/claude-code/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent and task management tools

> Reference for the Agent, TodoWrite, TaskCreate, TaskGet, TaskList, TaskUpdate, TaskStop, and MCPTool tools that enable multi-step and multi-agent workflows.

Claude has a set of tools for managing complex, multi-step work: spawning sub-agents, tracking tasks across a session, and calling tools on external MCP servers. These tools enable Claude to coordinate work that is too large or parallel for a single sequential conversation.

## Agent

Spawns a sub-agent to complete a self-contained task. The sub-agent runs with its own tool access and conversation context. The parent agent waits for the sub-agent to complete and then receives a result.

Use `Agent` when a task requires multiple steps that can be isolated — exploration, code analysis, test runs, or any work that benefits from a fresh context. For open-ended searches requiring multiple rounds of globbing or grepping, `Agent` is preferred over running the searches directly.

<Note>
  Sub-agents do not have access to `Agent` by default (to prevent unbounded recursion). They also cannot use `AskUserQuestion`, `TaskStop`, `ExitPlanMode`, or `EnterPlanMode`.
</Note>

### Inputs

<ParamField body="prompt" type="string" required>
  The task description for the sub-agent. Provide enough context for the sub-agent to work independently — it does not share the parent's conversation history.
</ParamField>

<ParamField body="system_prompt" type="string">
  Optional override for the sub-agent's system prompt.
</ParamField>

### Output

Returns the sub-agent's final response as a string. The sub-agent's intermediate tool calls are shown in the UI as a grouped block.

### Multi-agent workflows

`Agent` is the building block for multi-agent orchestration. A coordinator agent can spawn multiple sub-agents in parallel, each working on a separate part of a problem. Sub-agents report their results back to the coordinator, which synthesizes the final response.

In coordinator mode, the coordinator's tool access is limited to `Agent`, `TaskStop`, `SendMessage`, and output tools. All actual work is delegated to sub-agents.

***

## TodoWrite

Creates and manages a structured todo list for the current session. Tracks task status and progress. Each call replaces the current todo list with the provided list.

Use `TodoWrite` proactively for any task with 3 or more distinct steps. Mark tasks `in_progress` before starting them and `completed` immediately after finishing. Keep exactly one task `in_progress` at a time.

### Inputs

<ParamField body="todos" type="array" required>
  The full updated todo list. Each item has:

  * `content` — imperative description of the task (for example, `"Run tests"`)
  * `activeForm` — present continuous form shown during execution (for example, `"Running tests"`)
  * `status` — one of `"pending"`, `"in_progress"`, or `"completed"`
</ParamField>

### Output

<ResponseField name="oldTodos" type="array">
  The todo list before the update.
</ResponseField>

<ResponseField name="newTodos" type="array">
  The todo list after the update.
</ResponseField>

### When to use

Use `TodoWrite` when:

* A task requires 3 or more distinct steps
* The user provides multiple tasks (numbered list or comma-separated)
* The task requires careful planning across multiple operations
* You need to track progress to demonstrate thoroughness

Do not use `TodoWrite` for single, trivial tasks or purely conversational responses.

### Task states

| State         | Meaning                                            |
| ------------- | -------------------------------------------------- |
| `pending`     | Not yet started                                    |
| `in_progress` | Currently being worked on (limit to one at a time) |
| `completed`   | Finished successfully                              |

<Warning>
  Only mark a task `completed` when it is fully done. If you encounter errors or partial failures, keep the task `in_progress` and create a new task to track the blocker.
</Warning>

***

## TaskCreate

Creates a new task in the task list. Available to in-process teammates in multi-agent workflows.

### Inputs

<ParamField body="subject" type="string" required>
  A brief, actionable title for the task in imperative form (for example, `"Fix authentication bug in login flow"`).
</ParamField>

<ParamField body="description" type="string" required>
  What needs to be done. Include enough detail for another agent to understand and complete the task if it will be assigned to a teammate.
</ParamField>

<ParamField body="activeForm" type="string">
  Present continuous form shown in the spinner when the task is `in_progress` (for example, `"Fixing authentication bug"`). If omitted, the subject is shown instead.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value metadata to attach to the task.
</ParamField>

### Output

<ResponseField name="task.id" type="string">
  Identifier for the created task. Use this with `TaskGet`, `TaskUpdate`, and `TaskList`.
</ResponseField>

<ResponseField name="task.subject" type="string">
  The subject of the created task.
</ResponseField>

All tasks are created with status `pending` and no owner.

***

## TaskGet

Retrieves a task by ID. Returns the full task details including description, status, and dependency relationships.

### Inputs

<ParamField body="taskId" type="string" required>
  The ID of the task to retrieve.
</ParamField>

### Output

<ResponseField name="task" type="object">
  Full task details, or `null` if not found:

  * `id` — task identifier
  * `subject` — task title
  * `description` — full requirements
  * `status` — `"pending"`, `"in_progress"`, or `"completed"`
  * `blocks` — IDs of tasks waiting on this one
  * `blockedBy` — IDs of tasks that must complete before this one can start
</ResponseField>

### Notes

* Verify that `blockedBy` is empty before beginning work on a task.
* Use `TaskList` to see all tasks in summary form before fetching individual task details.

***

## TaskList

Lists all tasks in the task list with a summary of their current state. Use this to find available work, check overall progress, or identify blocked tasks.

### Output

Returns a summary of each task:

<ResponseField name="id" type="string">
  Task identifier for use with `TaskGet` and `TaskUpdate`.
</ResponseField>

<ResponseField name="subject" type="string">
  Brief description of the task.
</ResponseField>

<ResponseField name="status" type="string">
  `"pending"`, `"in_progress"`, or `"completed"`.
</ResponseField>

<ResponseField name="owner" type="string">
  Agent name if assigned, empty if available.
</ResponseField>

<ResponseField name="blockedBy" type="string[]">
  List of open task IDs that must be resolved before this task can start. Tasks with entries in `blockedBy` cannot be claimed.
</ResponseField>

### Teammate workflow

When working as a teammate in a multi-agent swarm:

1. After completing your current task, call `TaskList` to find available work.
2. Look for tasks with `status: "pending"`, no `owner`, and empty `blockedBy`.
3. Prefer tasks with lower IDs — earlier tasks often set up context for later ones.
4. Claim an available task using `TaskUpdate` (set `owner` to your agent name).

***

## TaskUpdate

Updates a task's status, owner, description, dependencies, or other fields. Available to in-process teammates in multi-agent workflows.

### Inputs

<ParamField body="taskId" type="string" required>
  The ID of the task to update.
</ParamField>

<ParamField body="status" type="string">
  New status for the task. Valid values: `"pending"`, `"in_progress"`, `"completed"`, `"deleted"`. Setting `"deleted"` permanently removes the task.
</ParamField>

<ParamField body="subject" type="string">
  New title for the task.
</ParamField>

<ParamField body="description" type="string">
  New description for the task.
</ParamField>

<ParamField body="activeForm" type="string">
  Present continuous form shown in the spinner when the task is `in_progress`.
</ParamField>

<ParamField body="owner" type="string">
  Agent name to assign the task to. Used to claim available tasks in a multi-agent swarm.
</ParamField>

<ParamField body="addBlocks" type="string[]">
  Task IDs that cannot start until this task completes.
</ParamField>

<ParamField body="addBlockedBy" type="string[]">
  Task IDs that must complete before this task can start.
</ParamField>

<ParamField body="metadata" type="object">
  Metadata keys to merge into the task. Set a key to `null` to remove it.
</ParamField>

### Status workflow

```text theme={null}
pending → in_progress → completed
```

Setting `status: "deleted"` permanently removes the task from the list.

<Warning>
  Read the task's latest state with `TaskGet` before updating it to avoid overwriting changes made by other agents.
</Warning>

### Example inputs

<CodeGroup>
  ```json Start working on a task theme={null}
  {
    "taskId": "1",
    "status": "in_progress"
  }
  ```

  ```json Complete a task theme={null}
  {
    "taskId": "1",
    "status": "completed"
  }
  ```

  ```json Claim a task as a teammate theme={null}
  {
    "taskId": "3",
    "owner": "my-agent-name"
  }
  ```

  ```json Set up a dependency theme={null}
  {
    "taskId": "2",
    "addBlockedBy": ["1"]
  }
  ```
</CodeGroup>

***

## TaskStop

Stops a running background task by ID.

### Inputs

<ParamField body="task_id" type="string" required>
  The ID of the background task to stop.
</ParamField>

### Output

Returns a success or failure status indicating whether the task was stopped.

***

## MCPTool

Calls a tool on a connected MCP (Model Context Protocol) server. The tool name, input schema, and description are provided by the MCP server at connection time — the `MCPTool` is a generic wrapper that is instantiated once per registered MCP tool.

Each MCP tool appears in Claude's tool list with its own name and schema as defined by the server. Claude calls it using the same inputs the server declared.

### Inputs

MCP tools use passthrough input validation — they accept any object matching the schema declared by the MCP server. The specific fields depend on the tool provided by the server.

### Output

Returns the MCP tool's execution result as a string.

### Permission requirements

Every MCP tool call requires a permission prompt. Claude presents the tool name and inputs before executing. You can approve individual calls or set allow rules for specific tool-and-input combinations.

### Notes

* MCP tools are only available when a compatible MCP server is connected to the session.
* If an MCP-provided web fetch tool is available, Claude will prefer it over the built-in `WebFetch` tool.
* The `MCPTool` itself cannot be used directly — it is instantiated per MCP tool via the MCP client at runtime.

***

## How these tools enable complex workflows

These tools work together to let Claude handle tasks that exceed a single sequential conversation:

<AccordionGroup>
  <Accordion title="Single-session task tracking with TodoWrite">
    For tasks with multiple steps, `TodoWrite` gives Claude and the user a shared view of what has been done and what remains. Claude updates task states in real time: marking items `in_progress` before starting and `completed` immediately after finishing. This makes it straightforward to resume work if interrupted.
  </Accordion>

  <Accordion title="Isolated sub-tasks with Agent">
    When part of a task can be done in isolation (code exploration, running a test suite, generating a file), `Agent` spawns a sub-agent with its own context. This avoids polluting the main conversation with intermediate steps and allows multiple sub-tasks to run in parallel.
  </Accordion>

  <Accordion title="Multi-agent coordination with Task tools">
    In multi-agent workflows, a coordinator creates tasks using `TaskCreate`, assigns them to teammates via `TaskUpdate`, and tracks overall progress using `TaskList`. Teammates use `TaskGet` to fetch their assignment, `TaskUpdate` to claim and complete it, and `TaskList` to find the next available task after finishing.
  </Accordion>

  <Accordion title="External tool integration with MCPTool">
    MCP servers extend Claude's tool set without requiring changes to Claude itself. A connected MCP server can expose database queries, CI/CD integrations, internal APIs, or any other capability as a callable tool. Claude discovers these tools at session start and calls them the same way as built-in tools.
  </Accordion>
</AccordionGroup>