Todoist AI MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

add-projects

Creates one or more new Todoist projects with optional sub-project, color, view style, favorite, workspace, and description settings so AI agents can organize work.

Instructions

Add one or more new projects.

Input Schema

Name	Required	Description	Default
`projects`	Yes	The array of projects to add.

Output Schema

Name	Required	Description
`failures`	Yes	Projects that could not be created, with the reason for each.
`projects`	Yes	The created projects.
`totalCount`	Yes	The total number of projects created.
`failureCount`	Yes
`successCount`	Yes
`totalRequested`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv13.8.4Nov 2, 2026
- changedInput schema / properties / projects / items / required
```
Previous value: -[
-  "name",
-  "color"
-]New value: +[
+  "name"
+]
```

Changed4 schema fields changedv13.8.0Oct 29, 2026

removedOutput schema / properties / failureCount / description
```
Removed value: -"The number of failed project creations."
```

changedOutput schema / properties / failures / description

Previous value: -"Projects that could not be created, with the reason for each. A failure here does not affect the other projects in the batch — do not retry the whole batch; address or drop the failed items."New value: +"Projects that could not be created, with the reason for each."

removedOutput schema / properties / successCount / description

Removed value: -"The number of successfully created projects."

removedOutput schema / properties / totalRequested / description
```
Removed value: -"The total number of projects requested."
```

Changed2 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"

changedOutput schema / $schema

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

Changed16 schema fields changedv12.5.3Aug 7, 2026
- removedOutput schema / properties / failures / items / properties / code / description
```
Removed value: -"The error code, if available."
```
- removedOutput schema / properties / failures / items / properties / error / description
```
Removed value: -"The error message."
```
- changedOutput schema / properties / failures / items / properties / item / description
```
Previous value: -"The item that failed (usually an ID or identifier)."New value: +"Usually the ID of the item that failed."
```
- changedOutput schema / properties / projects / items / properties / childOrder / description
```
Previous value: -"The ordering index of the project among its siblings."New value: +"Ordering index among siblings."
```
- removedOutput schema / properties / projects / items / properties / color / description
```
Removed value: -"The color key of the entity."
```
- changedOutput schema / properties / projects / items / properties / description / description
```
Previous value: -"The description of the project (empty string if none)."New value: +"Empty string when none."
```
- changedOutput schema / properties / projects / items / properties / folderId / description
```
Previous value: -"The ID of the folder this project belongs to (workspace projects only)."New value: +"Workspace projects only."
```
- removedOutput schema / properties / projects / items / properties / id / description
```
Removed value: -"The unique ID of the project."
```
- removedOutput schema / properties / projects / items / properties / inboxProject / description
```
Removed value: -"Whether this is the inbox project."
```
- removedOutput schema / properties / projects / items / properties / isArchived / description
```
Removed value: -"Whether the project is archived."
```
- removedOutput schema / properties / projects / items / properties / isFavorite / description
```
Removed value: -"Whether the project is marked as favorite."
```
- removedOutput schema / properties / projects / items / properties / isShared / description
```
Removed value: -"Whether the project is shared."
```
- removedOutput schema / properties / projects / items / properties / name / description
```
Removed value: -"The name of the project."
```
- removedOutput schema / properties / projects / items / properties / parentId / description
```
Removed value: -"The ID of the parent project (for sub-projects)."
```
- changedOutput schema / properties / projects / items / properties / viewStyle / description
```
Previous value: -"The view style of the project (list, board, calendar)."New value: +"list, board or calendar."
```
- changedOutput schema / properties / projects / items / properties / workspaceId / description
```
Previous value: -"The ID of the workspace this project belongs to (undefined for personal projects)."New value: +"Undefined for personal projects."
```

Changed5 schema fields changedv12.2.4Aug 3, 2026

addedOutput schema / properties / failureCount

Added value: +{
+  "description": "The number of failed project creations.",
+  "type": "number"
+}

addedOutput schema / properties / failures

Added value: +{
+  "description": "Projects that could not be created, with the reason for each. A failure here does not affect the other projects in the batch — do not retry the whole batch; address or drop the failed items.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "code": {
+        "description": "The error code, if available.",
+        "type": "string"
+      },
+      "error": {
+        "description": "The error message.",
+        "type": "string"
+      },
+      "item": {
+        "description": "The item that failed (usually an ID or identifier).",
+        "type": "string"
+      }
+    },
+    "required": [
+      "item",
+      "error"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / successCount

Added value: +{
+  "description": "The number of successfully created projects.",
+  "type": "number"
+}

addedOutput schema / properties / totalRequested

Added value: +{
+  "description": "The total number of projects requested.",
+  "type": "number"
+}

changedOutput schema / required

Previous value: -[
-  "projects",
-  "totalCount"
-]New value: +[
+  "projects",
+  "totalCount",
+  "failures",
+  "totalRequested",
+  "successCount",
+  "failureCount"
+]

First observedv10.4.2Jul 9, 2026

TDQS

C2.9/5.0

Behavior2/5

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

Annotations already disclose that this is a non-read-only, non-idempotent, non-destructive mutation. The description adds no behavioral context such as duplicate handling, required permissions, or side effects beyond what annotations provide.

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

Conciseness3/5

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

The single sentence is front-loaded and free of fluff, but it is severely under-specified for a creation tool with a rich nested schema. Brevity here reflects omission rather than optimized conciseness.

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

Completeness3/5

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

The schema and annotations cover most invocation details, and the output schema means return values need not be described. However, the description lacks usage and behavioral context that would help an agent choose and call this tool confidently.

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%, and the nested project fields are fully documented in the schema. The description adds no parameter meaning beyond the schema, so the baseline of 3 is appropriate.

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

Purpose4/5

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

The description states a specific verb and resource: 'Add one or more new projects.' It clearly conveys project creation and batch scope, but does not differentiate from siblings such as update-projects or add-tasks.

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

Usage Guidelines2/5

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

The description provides no when-to-use guidance, prerequisites, or alternatives. It does not mention when to choose add-projects over update-projects or find-projects.

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