Skip to main content
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.
Sub-agents do not have access to Agent by default (to prevent unbounded recursion). They also cannot use AskUserQuestion, TaskStop, ExitPlanMode, or EnterPlanMode.

​
Inputs

​
prompt
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.
​
system_prompt
string
Optional override for the sub-agent’s system prompt.

​
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

​
todos
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"

​
Output

​
oldTodos
array
The todo list before the update.
​
newTodos
array
The todo list after the update.

​
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

StateMeaning
pendingNot yet started
in_progressCurrently being worked on (limit to one at a time)
completedFinished successfully
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.

​
TaskCreate

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

​
Inputs

​
subject
string
required
A brief, actionable title for the task in imperative form (for example, "Fix authentication bug in login flow").
​
description
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.
​
activeForm
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.
​
metadata
object
Arbitrary key-value metadata to attach to the task.

​
Output

​
task.id
string
Identifier for the created task. Use this with TaskGet, TaskUpdate, and TaskList.
​
task.subject
string
The subject of the created task.
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

​
taskId
string
required
The ID of the task to retrieve.

​
Output

​
task
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

​
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:
​
id
string
Task identifier for use with TaskGet and TaskUpdate.
​
subject
string
Brief description of the task.
​
status
string
"pending", "in_progress", or "completed".
​
owner
string
Agent name if assigned, empty if available.
​
blockedBy
string[]
List of open task IDs that must be resolved before this task can start. Tasks with entries in blockedBy cannot be claimed.

​
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

​
taskId
string
required
The ID of the task to update.
​
status
string
New status for the task. Valid values: "pending", "in_progress", "completed", "deleted". Setting "deleted" permanently removes the task.
​
subject
string
New title for the task.
​
description
string
New description for the task.
​
activeForm
string
Present continuous form shown in the spinner when the task is in_progress.
​
owner
string
Agent name to assign the task to. Used to claim available tasks in a multi-agent swarm.
​
addBlocks
string[]
Task IDs that cannot start until this task completes.
​
addBlockedBy
string[]
Task IDs that must complete before this task can start.
​
metadata
object
Metadata keys to merge into the task. Set a key to null to remove it.

​
Status workflow

pending → in_progress → completed
Setting status: "deleted" permanently removes the task from the list.
Read the task’s latest state with TaskGet before updating it to avoid overwriting changes made by other agents.

​
Example inputs

{
  "taskId": "1",
  "status": "in_progress"
}

​
TaskStop

Stops a running background task by ID.

​
Inputs

​
task_id
string
required
The ID of the background task to stop.

​
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:
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.
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.
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.
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us