Todoist MCP Server

get-overview

Read-onlyIdempotent

Retrieve a Markdown overview of Todoist projects and sections. Provide a project ID to view its tasks grouped by section, or omit it to see the account's structure 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.

First observedv13.3.1Sep 22, 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.