Todoist AI MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

add-projects

Create one or more new Todoist projects, optionally as sub-projects with a chosen workspace, color, and view style. Add project names and settings in a single call.

Instructions

Add one or more new projects.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "projects": "<projects>"
    },
    "name": "add-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.

Changed2 schema fields changedv13.10.1Nov 5, 2026
- changedInput schema / properties / projects / items / properties / viewStyle / enum
```
Previous value: -[
-  "list",
-  "board",
-  "calendar"
-]New value: +[
+  "list",
+  "board",
+  "calendar",
+  "table"
+]
```
- changedOutput schema / properties / projects / items / properties / viewStyle / description
```
Previous value: -"list, board or calendar."New value: +"list, board, calendar or table."
```
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?

The annotations already state readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, which covers the safety and mutability profile. The description adds nothing beyond that — no note about batch atomicity (does one bad project fail the whole array?), no default-to-personal-project behavior, and no permission expectations, even though non-idempotent batch creation is exactly where that context matters.

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 waste, but it is under-specified rather than genuinely concise. There is no structure to speak of — no secondary sentence covering prerequisites, batch behavior, or sibling routing.

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?

An output schema exists, annotations cover the safety profile, and the schema documents every field, so the description needn't explain return values or parameters. For a non-idempotent, potentially batch-mutating tool, however, omitting batch failure semantics and calls out to list-workspaces (mentioned only in the schema) leaves the definition thin.

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 (name, color, parentId, workspace, viewStyle, isFavorite, description) are all documented in the schema itself. The description's "one or more" loosely restates minItems 1 but contributes no additional meaning, so the baseline 3 applies.

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 gives a specific verb ("Add") and resource ("new projects") plus a quantity hint ("one or more"). It is clear what the tool does, but it never names or contrasts with siblings like update-projects or import-project-template, leaving differentiation to the schema.

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?

There is no when-to-use guidance, no prerequisites, and no alternatives named. Nothing tells an agent whether this is the right tool versus update-projects (for existing projects) or import-project-template (for bulk imports), so selection must be inferred 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.