Todoist AI MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

add-filters

Create one or more personal filters—saved custom views using query syntax—to organize tasks by criteria like priority, project, or due date.

Instructions

Add one or more new personal filters. Filters are saved custom views using query syntax to organize tasks.

Input Schema

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

Output Schema

Name	Required	Description
`filters`	Yes	The created filters.
`failures`	Yes	Filters that could not be created, with the reason for each.
`totalCount`	Yes	The total number of filters 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 / filters / items / required
```
Previous value: -[
-  "name",
-  "query",
-  "color"
-]New value: +[
+  "name",
+  "query"
+]
```

Changed5 schema fields changedv13.8.0Oct 29, 2026

addedOutput schema / properties / failureCount
```
Added value: +{
+  "type": "number"
+}
```

addedOutput schema / properties / failures

Added value: +{
+  "description": "Filters that could not be created, with the reason for each.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "code": {
+        "type": "string"
+      },
+      "error": {
+        "type": "string"
+      },
+      "item": {
+        "description": "Usually the ID of the item that failed.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "item",
+      "error"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / successCount
```
Added value: +{
+  "type": "number"
+}
```
addedOutput schema / properties / totalRequested
```
Added value: +{
+  "type": "number"
+}
```

changedOutput schema / required

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

Changed2 schema fields changedv13.2.1Sep 4, 2026

addedInput schema / properties / filters / items / properties / description

Added value: +{
+  "description": "A markdown description explaining what the filter is for.",
+  "type": "string"
+}

addedOutput schema / properties / filters / items / properties / description

Added value: +{
+  "description": "A markdown description explaining what the filter is for. Omitted when the filter has none.",
+  "type": "string"
+}

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"

Changed1 schema field changedv12.5.3Aug 7, 2026
- removedOutput schema / properties / filters / items / properties / color / description
```
Removed value: -"The color key of the entity."
```
First observedv10.4.2Jul 9, 2026

TDQS

A3.6/5.0

Behavior3/5

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

Annotations already declare this as a non-read-only, non-idempotent, non-destructive mutation. The description adds useful domain context that filters are personal saved views using query syntax, but it does not disclose duplicate-name behavior, validation failures, or what is returned.

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?

The description is two concise sentences with no wasted wording. The primary action is front-loaded, followed by a useful clarification of what a filter is.

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

Completeness4/5

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

For a simple create operation with full schema coverage, annotations, and an output schema, the description is largely complete. A minor gap is that it does not mention duplicate handling or error behavior, but nothing essential for invocation 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%, so the schema already documents the filters array, required name and query fields, color, favorite status, and description. The description only adds that one or more filters are accepted and that queries use syntax, matching rather than exceeding the schema baseline.

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: adding new personal filters, described as saved custom views using query syntax. It distinguishes creation from updating or finding filters only implicitly through 'new', but an agent can tell what the tool does.

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

Usage Guidelines3/5

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

Usage is implied: use this when creating one or more new personal filters. However, the description does not explicitly contrast with update-filters or find-filters, nor does it state conditions such as handling existing filters.

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