Todoist AI MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

get-overview

Read-onlyIdempotent

Get an overview of Todoist projects and sections. Use a project ID to list tasks grouped by section, or omit it for a navigation view without tasks.

Instructions

Get a Markdown overview. Called without a projectId, returns the account's project and section structure only — no tasks — for navigation. Pass a projectId (or "inbox" for the Inbox) to get that project's tasks grouped by section.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`projectId`	No	Optional project ID. Use "inbox" for the Inbox. If provided, returns that project's tasks grouped by section. If omitted, returns the project and section structure for the whole account with no tasks.

Output Schema

TableJSON Schema

Name	Required	Description
`type`	Yes	The type of overview returned.
`inbox`	No	Inbox information (account overview only).
`stats`	No	Statistics object (project overview only).
`tasks`	No	List of tasks (project overview only).
`project`	No	Project details (project overview only).
`projects`	No	List of projects with hierarchy, folders, and ordering (account overview only).
`sections`	No	List of sections (project overview only).
`totalTasks`	No	Total number of tasks.
`projectInfo`	No	Project information (project overview only).
`totalProjects`	No	Total number of projects (account overview only).
`totalSections`	No	Total number of sections (project overview only).
`hasNestedProjects`	No	Whether account has nested projects (account overview only).
`tasksWithoutSection`	No	Number of tasks not in any section (project overview only).

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv13.2.6Sep 15, 2026

changedInput schema / properties / projectId / description

Previous value: -"Optional project ID. Use \"inbox\" for the Inbox. If provided, shows detailed overview of that project. If omitted, shows overview of all projects."New value: +"Optional project ID. Use \"inbox\" for the Inbox. If provided, returns that project's tasks grouped by section. If omitted, returns the project and section structure for the whole account with no tasks."

Changed1 schema field changedv13.2.4Sep 10, 2026

changedInput schema / properties / projectId / description

Previous value: -"Optional project ID. If provided, shows detailed overview of that project. If omitted, shows overview of all projects."New value: +"Optional project ID. Use \"inbox\" for the Inbox. If provided, shows detailed overview of that project. If omitted, shows overview of all projects."

Changed3 schema fields changedv13.1.3Sep 2, 2026
- addedOutput schema / $defs / __schema0 / properties / sections / items / properties / description
```
Added value: +{
+  "description": "Supports Markdown.",
+  "type": "string"
+}
```
- addedOutput schema / $defs / __schema0 / properties / sections / items / properties / sectionOrder
```
Added value: +{
+  "description": "Ordering index within the project.",
+  "type": "number"
+}
```
- changedOutput schema / $defs / __schema0 / properties / sections / items / required
```
Previous value: -[
-  "id",
-  "name"
-]New value: +[
+  "id",
+  "name",
+  "sectionOrder"
+]
```

Changed6 schema fields changedv13.0.0Aug 20, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / $defs

Added value: +{
+  "__schema0": {
+    "additionalProperties": false,
+    "properties": {
+      "childOrder": {
+        "description": "The ordering index among siblings.",
+        "type": "number"
+      },
+      "children": {
+        "description": "Nested child projects.",
+        "items": {
+          "$ref": "#/$defs/__schema0"
+        },
+        "type": "array"
+      },
+      "folderId": {
+        "description": "The folder ID this project belongs to (workspace projects only).",
+        "type": "string"
+      },
+      "id": {
+        "description": "The project ID.",
+        "type": "string"
+      },
+      "name": {
+        "description": "The project name.",
+        "type": "string"
+      },
+      "parentId": {
+        "description": "The parent project ID (for sub-projects, personal projects only).",
+        "type": "string"
+      },
+      "sections": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "name"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "id",
+      "name",
+      "childOrder",
+      "sections",
+      "children"
+    ],
+    "type": "object"
+  }
+}

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

removedOutput schema / definitions

Removed value: -{
-  "__schema0": {
-    "additionalProperties": false,
-    "properties": {
-      "childOrder": {
-        "description": "The ordering index among siblings.",
-        "type": "number"
-      },
-      "children": {
-        "description": "Nested child projects.",
-        "items": {
-          "$ref": "#/definitions/__schema0"
-        },
-        "type": "array"
-      },
-      "folderId": {
-        "description": "The folder ID this project belongs to (workspace projects only).",
-        "type": "string"
-      },
-      "id": {
-        "description": "The project ID.",
-        "type": "string"
-      },
-      "name": {
-        "description": "The project name.",
-        "type": "string"
-      },
-      "parentId": {
-        "description": "The parent project ID (for sub-projects, personal projects only).",
-        "type": "string"
-      },
-      "sections": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "id": {
-              "type": "string"
-            },
-            "name": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "id",
-            "name"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      }
-    },
-    "required": [
-      "id",
-      "name",
-      "childOrder",
-      "sections",
-      "children"
-    ],
-    "type": "object"
-  }
-}

addedOutput schema / properties / projects / items / $ref
```
Added value: +"#/$defs/__schema0"
```

removedOutput schema / properties / projects / items / allOf

Removed value: -[
-  {
-    "$ref": "#/definitions/__schema0"
-  }
-]

Changed5 schema fields changedv12.5.6Aug 12, 2026

addedOutput schema / properties / inbox / additionalProperties
```
Added value: +false
```

removedOutput schema / properties / inbox / anyOf

Removed value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "id": {
-        "description": "The inbox project ID.",
-        "type": "string"
-      },
-      "name": {
-        "description": "The inbox project name.",
-        "type": "string"
-      },
-      "sections": {
-        "description": "Sections in the inbox project.",
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "description": {
-              "description": "Supports Markdown.",
-              "type": "string"
-            },
-            "id": {
-              "type": "string"
-            },
-            "name": {
-              "type": "string"
-            },
-            "sectionOrder": {
-              "description": "Ordering index within the project.",
-              "type": "number"
-            }
-          },
-          "required": [
-            "id",
-            "name",
-            "sectionOrder"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      }
-    },
-    "required": [
-      "id",
-      "name",
-      "sections"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / inbox / properties

Added value: +{
+  "id": {
+    "description": "The inbox project ID.",
+    "type": "string"
+  },
+  "name": {
+    "description": "The inbox project name.",
+    "type": "string"
+  },
+  "sections": {
+    "description": "Sections in the inbox project.",
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "description": {
+          "description": "Supports Markdown.",
+          "type": "string"
+        },
+        "id": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "sectionOrder": {
+          "description": "Ordering index within the project.",
+          "type": "number"
+        }
+      },
+      "required": [
+        "id",
+        "name",
+        "sectionOrder"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  }
+}

addedOutput schema / properties / inbox / required

Added value: +[
+  "id",
+  "name",
+  "sections"
+]

addedOutput schema / properties / inbox / type
```
Added value: +"object"
```

Changed5 schema fields changedv12.5.3Aug 7, 2026

changedOutput schema / properties / inbox / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "id": {
-        "description": "The inbox project ID.",
-        "type": "string"
-      },
-      "name": {
-        "description": "The inbox project name.",
-        "type": "string"
-      },
-      "sections": {
-        "description": "Sections in the inbox project.",
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "description": {
-              "description": "The description of the section. Supports Markdown.",
-              "type": "string"
-            },
-            "id": {
-              "description": "The unique ID of the section.",
-              "type": "string"
-            },
-            "name": {
-              "description": "The name of the section.",
-              "type": "string"
-            },
-            "sectionOrder": {
-              "description": "The ordering index of the section within its project.",
-              "type": "number"
-            }
-          },
-          "required": [
-            "id",
-            "name",
-            "sectionOrder"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      }
-    },
-    "required": [
-      "id",
-      "name",
-      "sections"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "description": "The inbox project ID.",
+        "type": "string"
+      },
+      "name": {
+        "description": "The inbox project name.",
+        "type": "string"
+      },
+      "sections": {
+        "description": "Sections in the inbox project.",
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "description": {
+              "description": "Supports Markdown.",
+              "type": "string"
+            },
+            "id": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            },
+            "sectionOrder": {
+              "description": "Ordering index within the project.",
+              "type": "number"
+            }
+          },
+          "required": [
+            "id",
+            "name",
+            "sectionOrder"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "id",
+      "name",
+      "sections"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / sections / items / properties / description / description

Previous value: -"The description of the section. Supports Markdown."New value: +"Supports Markdown."

removedOutput schema / properties / sections / items / properties / id / description
```
Removed value: -"The unique ID of the section."
```
removedOutput schema / properties / sections / items / properties / name / description
```
Removed value: -"The name of the section."
```

changedOutput schema / properties / sections / items / properties / sectionOrder / description

Previous value: -"The ordering index of the section within its project."New value: +"Ordering index within the project."

Changed3 schema fields changedv12.1.2Jul 27, 2026

changedOutput schema / properties / inbox / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "id": {
-        "description": "The inbox project ID.",
-        "type": "string"
-      },
-      "name": {
-        "description": "The inbox project name.",
-        "type": "string"
-      },
-      "sections": {
-        "description": "Sections in the inbox project.",
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "description": {
-              "description": "The description of the section. Supports Markdown.",
-              "type": "string"
-            },
-            "id": {
-              "description": "The unique ID of the section.",
-              "type": "string"
-            },
-            "name": {
-              "description": "The name of the section.",
-              "type": "string"
-            }
-          },
-          "required": [
-            "id",
-            "name"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      }
-    },
-    "required": [
-      "id",
-      "name",
-      "sections"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "description": "The inbox project ID.",
+        "type": "string"
+      },
+      "name": {
+        "description": "The inbox project name.",
+        "type": "string"
+      },
+      "sections": {
+        "description": "Sections in the inbox project.",
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "description": {
+              "description": "The description of the section. Supports Markdown.",
+              "type": "string"
+            },
+            "id": {
+              "description": "The unique ID of the section.",
+              "type": "string"
+            },
+            "name": {
+              "description": "The name of the section.",
+              "type": "string"
+            },
+            "sectionOrder": {
+              "description": "The ordering index of the section within its project.",
+              "type": "number"
+            }
+          },
+          "required": [
+            "id",
+            "name",
+            "sectionOrder"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "id",
+      "name",
+      "sections"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

addedOutput schema / properties / sections / items / properties / sectionOrder

Added value: +{
+  "description": "The ordering index of the section within its project.",
+  "type": "number"
+}

changedOutput schema / properties / sections / items / required

Previous value: -[
-  "id",
-  "name"
-]New value: +[
+  "id",
+  "name",
+  "sectionOrder"
+]

First observedv10.4.2Jul 9, 2026

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value beyond annotations by disclosing the Markdown return format, the parameter-dependent mode switch, the exclusion of tasks in the account-wide view, and section grouping behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with zero waste. The primary deliverable (Markdown overview) is front-loaded, and the mode-dependent behavior is packed into a compact second sentence that covers both call variants.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, single-optional-parameter tool with annotations covering safety and an output schema present, the description fully covers invocation modes, output format, and scope. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% — the schema already documents projectId, the 'inbox' special value, and the two behavioral outcomes. The description reinforces this but adds minimal new meaning beyond the schema's own parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description states a specific verb and resource ('Get a Markdown overview') and precisely distinguishes the two invocation modes: account structure without a projectId versus tasks grouped by section with one. This clearly differentiates it from siblings like find-tasks, find-projects, and get-productivity-stats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use conditions for both modes: omit projectId for navigation structure only, or pass projectId/'inbox' to get tasks grouped by section. It implies the alternative use cases (navigating vs. retrieving tasks) but does not name sibling tools explicitly or state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.