Todoist MCP Server

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'uses Sync API', which hints at the underlying mechanism but doesn't clarify key behaviors like rate limits, authentication requirements, pagination defaults (beyond the schema's 'limit' default), or what the output looks like (no output schema exists). For a read operation with 7 parameters, this leaves significant gaps in understanding how the tool behaves.

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

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

The description is extremely concise—just one sentence—and front-loaded with the core purpose. Every word earns its place: 'List completed tasks' states the action, '(uses Sync API)' adds implementation context, and 'with optional filters' hints at flexibility. There's no wasted verbiage or redundancy.

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

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

Given the tool's complexity (7 parameters, no annotations, no output schema), the description is insufficient. It doesn't address behavioral aspects like pagination handling, error conditions, or output format. While the schema covers parameters, the lack of annotations and output schema means the description should compensate more to help the agent use the tool effectively, which it fails to do.

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

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

Schema description coverage is 100%, so the schema fully documents all 7 parameters. The description adds minimal value beyond the schema by mentioning 'optional filters', which is implied by the parameter names. It doesn't provide additional context like filter combinations or precedence rules. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't significantly enhance parameter understanding.

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

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

The description clearly states the tool's purpose: 'List completed tasks (uses Sync API) with optional filters'. It specifies the verb ('List'), resource ('completed tasks'), and implementation detail ('uses Sync API'). However, it doesn't explicitly differentiate from sibling tools like 'todoist_list_tasks' or 'todoist_search_tasks', which is why it doesn't achieve a perfect score.

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

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

The description provides minimal guidance: it mentions 'optional filters' but doesn't specify when to use this tool versus alternatives like 'todoist_list_tasks' (for active tasks) or 'todoist_search_tasks' (for broader searches). There's no explicit context about when this tool is preferred or when to avoid it, leaving the agent to infer usage from the name alone.

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