Document todo tool (#11695)

docs/tools/index.md

@@ -86,6 +86,8 @@ Gemini CLI's built-in tools can be broadly categorized as follows:
   tool for reading content from multiple files or directories.
 - **[Memory Tool](./memory.md) (`save_memory`):** For saving and recalling
   information across sessions.
+- **[Todo Tool](./todos.md) (`write_todos`):** For managing subtasks of complex
+  requests.
 
 Additionally, these tools incorporate:
 

docs/tools/todos.md

@@ -0,0 +1,56 @@
+# Todo Tool (`write_todos`)
+
+This document describes the `write_todos` tool for the Gemini CLI.
+
+## Description
+
+The `write_todos` tool allows the Gemini agent to create and manage a list of
+subtasks for complex user requests. This provides you, the user, with greater
+visibility into the agent's plan and its current progress.
+
+### Arguments
+
+`write_todos` takes one argument:
+
+- `todos` (array of objects, required): The complete list of todo items. This
+  replaces the existing list. Each item includes:
+  - `description` (string): The task description.
+  - `status` (string): The current status (`pending`, `in_progress`,
+    `completed`, or `cancelled`).
+
+## Behavior
+
+The agent uses this tool to break down complex multi-step requests into a clear
+plan.
+
+- **Progress Tracking:** The agent updates this list as it works, marking tasks
+  as `completed` when done.
+- **Single Focus:** Only one task will be marked `in_progress` at a time,
+  indicating exactly what the agent is currently working on.
+- **Dynamic Updates:** The plan may evolve as the agent discovers new
+  information, leading to new tasks being added or unnecessary ones being
+  cancelled.
+
+When active, the current `in_progress` task is displayed above the input box,
+keeping you informed of the immediate action. You can toggle the full view of
+the todo list at any time by pressing `Ctrl+T`.
+
+Usage example (internal representation):
+
+```javascript
+write_todos({
+  todos: [
+    { description: 'Initialize new React project', status: 'completed' },
+    { description: 'Implement state management', status: 'in_progress' },
+    { description: 'Create API service', status: 'pending' },
+  ],
+});
+```
+
+## Important notes
+
+- **Enabling:** This tool is disabled by default. To use it, you must enable it
+  in your `settings.json` file by setting `"useWriteTodos": true`.
+
+- **Intended Use:** This tool is primarily used by the agent for complex,
+  multi-turn tasks. It is generally not used for simple, single-turn questions.