Plain text · sha256 995575dbea8f
The description, line by line
40 lines Line numbers are v2.1.269 on the left and this capture on the right.
1
1
Use this tool to create a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
2
2
It also helps the user understand the progress of the task and overall progress of their requests.
3
3
4
4
## When to Use This Tool
5
5
6
6
Use this tool proactively in these scenarios:
7
7
8
8
- Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
9
9
- Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
10
10
- Plan mode - When using plan mode, create a task list to track the work
11
11
- User explicitly requests todo list - When the user directly asks you to use the todo list
12
12
- User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
13
13
- After receiving new instructions - Immediately capture user requirements as tasks
14
14
- When you start working on a task - Mark it as in_progress BEFORE beginning work
15
15
- After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
16
16
17
17
## When NOT to Use This Tool
18
18
19
19
Skip using this tool when:
20
20
- There is only a single, straightforward task
21
21
- The task is trivial and tracking it provides no organizational benefit
22
22
- The task can be completed in less than 3 trivial steps
23
23
- The task is purely conversational or informational
24
24
25
25
NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.
26
26
27
27
## Task Fields
28
28
29
29
- **subject**: A brief, actionable title in imperative form (e.g., "Fix authentication bug in login flow")
30
30
- **description**: What needs to be done
31
31
- **activeForm** (optional): Present continuous form shown in the spinner when the task is in_progress (e.g., "Fixing authentication bug"). If omitted, the spinner shows the subject instead.
32
32
33
33
All tasks are created with status `pending`.
34
34
35
35
## Tips
36
36
37
37
- Create tasks with clear, specific subjects that describe the outcome
38
38
- After creating tasks, use TaskUpdate to set up dependencies (blocks/blockedBy) if needed
39
39
- Check TaskList first to avoid creating duplicate tasks
40
40
What it accepts
4 parameters The JSON parameter schema sent beside this description, 687 characters of it. Name, type, then whether the client marked it required.activeForm
string
optional
Present continuous form shown in spinner when in_progress (e.g., "Running tests")
description
string
required
What needs to be done
metadata
object
optional
Arbitrary metadata to attach to the task
subject
string
required
A brief title for the task
sha256 f08c2d6156af · the schema as the client sent it:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"activeForm": {
"description": "Present continuous form shown in spinner when in_progress (e.g., \"Running tests\")",
"type": "string"
},
"description": {
"description": "What needs to be done",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"description": "Arbitrary metadata to attach to the task",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"subject": {
"description": "A brief title for the task",
"type": "string"
}
},
"required": [
"subject",
"description"
],
"type": "object"
}