Todoist AI MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

add-reminders

Add relative, absolute, or location-based reminders to Todoist tasks so users get notified before due dates, at set times, or when entering or leaving a place.

Instructions

Add reminders to tasks. Supports three types: "relative" (minutes before due), "absolute" (specific date/time), or "location" (geofence-triggered). Each reminder must specify a taskId. Reminders notify their creator unless notifyUser says otherwise.

Input Schema

Name	Required	Description	Default
`reminders`	Yes	Array of reminders to create (max 25). Each reminder must specify a type: "relative" (minutes before due), "absolute" (specific date/time), or "location" (geofence trigger).

Output Schema

Name	Required	Description
`failures`	Yes	Reminders that could not be created, with the reason for each.
`reminders`	Yes	The created reminders.
`totalCount`	Yes	Total number of reminders created.
`failureCount`	Yes
`successCount`	Yes
`totalRequested`	Yes
`addedReminderIds`	Yes	IDs of the created reminders.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv13.8.0Oct 29, 2026

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

addedOutput schema / properties / failures

Added value: +{
+  "description": "Reminders 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: -[
-  "reminders",
-  "totalCount",
-  "addedReminderIds"
-]New value: +[
+  "reminders",
+  "totalCount",
+  "addedReminderIds",
+  "failures",
+  "totalRequested",
+  "successCount",
+  "failureCount"
+]

Changed2 schema fields changedv13.7.0Oct 27, 2026

changedInput schema / properties / reminders / items / oneOf

Previous value: -[
-  {
-    "properties": {
-      "isUrgent": {
-        "description": "Whether this is an urgent reminder. Applies to relative and absolute reminders.",
-        "type": "boolean"
-      },
-      "minuteOffset": {
-        "description": "Minutes before the task due time to trigger the reminder. E.g., 30 for 30 minutes before, 60 for 1 hour before, 1440 for 1 day before.",
-        "maximum": 9007199254740991,
-        "minimum": 0,
-        "type": "integer"
-      },
-      "service": {
-        "description": "Delivery method: \"email\" or \"push\" notification. Defaults to push.",
-        "enum": [
-          "email",
-          "push"
-        ],
-        "type": "string"
-      },
-      "taskId": {
-        "description": "The ID of the task to set a reminder for.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "type": {
-        "const": "relative",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "taskId",
-      "minuteOffset"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "due": {
-        "description": "The specific date/time for the reminder.",
-        "properties": {
-          "date": {
-            "description": "Due date in YYYY-MM-DD format.",
-            "type": "string"
-          },
-          "lang": {
-            "description": "Language for parsing the due string, e.g. \"en\".",
-            "type": "string"
-          },
-          "string": {
-            "description": "Natural language due string, e.g. \"tomorrow at 3pm\".",
-            "type": "string"
-          },
-          "timezone": {
-            "description": "Timezone for the reminder, e.g. \"America/New_York\".",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      },
-      "isUrgent": {
-        "description": "Whether this is an urgent reminder. Applies to relative and absolute reminders.",
-        "type": "boolean"
-      },
-      "service": {
-        "description": "Delivery method: \"email\" or \"push\" notification. Defaults to push.",
-        "enum": [
-          "email",
-          "push"
-        ],
-        "type": "string"
-      },
-      "taskId": {
-        "description": "The ID of the task to set a reminder for.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "type": {
-        "const": "absolute",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "taskId",
-      "due"
-    ],
-    "type": "object"
-  },
-  {
-    "properties": {
-      "locLat": {
-        "description": "Latitude of the location as a string, e.g. \"37.7749\".",
-        "type": "string"
-      },
-      "locLong": {
-        "description": "Longitude of the location as a string, e.g. \"-122.4194\".",
-        "type": "string"
-      },
-      "locTrigger": {
-        "description": "When to trigger: \"on_enter\" (arriving) or \"on_leave\" (departing).",
-        "enum": [
-          "on_enter",
-          "on_leave"
-        ],
-        "type": "string"
-      },
-      "name": {
-        "description": "Name of the location, e.g. \"Office\", \"Home\".",
-        "minLength": 1,
-        "type": "string"
-      },
-      "radius": {
-        "description": "Radius in meters for the geofence. Defaults to server default.",
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      "taskId": {
-        "description": "The ID of the task to set a reminder for.",
-        "minLength": 1,
-        "type": "string"
-      },
-      "type": {
-        "const": "location",
-        "type": "string"
-      }
-    },
-    "required": [
-      "type",
-      "taskId",
-      "name",
-      "locLat",
-      "locLong",
-      "locTrigger"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "properties": {
+      "isUrgent": {
+        "description": "Whether this is an urgent reminder. Applies to relative and absolute reminders.",
+        "type": "boolean"
+      },
+      "minuteOffset": {
+        "description": "Minutes before the task due time to trigger the reminder. E.g., 30 for 30 minutes before, 60 for 1 hour before, 1440 for 1 day before.",
+        "maximum": 9007199254740991,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "notifyUser": {
+        "description": "Who to remind: user ID, email, name, or \"me\". Must collaborate on the task's project. Defaults to the creator.",
+        "type": "string"
+      },
+      "service": {
+        "description": "Delivery method: \"email\" or \"push\" notification. Defaults to push.",
+        "enum": [
+          "email",
+          "push"
+        ],
+        "type": "string"
+      },
+      "taskId": {
+        "description": "The ID of the task to set a reminder for.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "type": {
+        "const": "relative",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "taskId",
+      "minuteOffset"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "due": {
+        "description": "The specific date/time for the reminder.",
+        "properties": {
+          "date": {
+            "description": "Due date in YYYY-MM-DD format.",
+            "type": "string"
+          },
+          "lang": {
+            "description": "Language for parsing the due string, e.g. \"en\".",
+            "type": "string"
+          },
+          "string": {
+            "description": "Natural language due string, e.g. \"tomorrow at 3pm\".",
+            "type": "string"
+          },
+          "timezone": {
+            "description": "Timezone for the reminder, e.g. \"America/New_York\".",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "isUrgent": {
+        "description": "Whether this is an urgent reminder. Applies to relative and absolute reminders.",
+        "type": "boolean"
+      },
+      "notifyUser": {
+        "description": "Who to remind: user ID, email, name, or \"me\". Must collaborate on the task's project. Defaults to the creator.",
+        "type": "string"
+      },
+      "service": {
+        "description": "Delivery method: \"email\" or \"push\" notification. Defaults to push.",
+        "enum": [
+          "email",
+          "push"
+        ],
+        "type": "string"
+      },
+      "taskId": {
+        "description": "The ID of the task to set a reminder for.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "type": {
+        "const": "absolute",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "taskId",
+      "due"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "locLat": {
+        "description": "Latitude of the location as a string, e.g. \"37.7749\".",
+        "type": "string"
+      },
+      "locLong": {
+        "description": "Longitude of the location as a string, e.g. \"-122.4194\".",
+        "type": "string"
+      },
+      "locTrigger": {
+        "description": "When to trigger: \"on_enter\" (arriving) or \"on_leave\" (departing).",
+        "enum": [
+          "on_enter",
+          "on_leave"
+        ],
+        "type": "string"
+      },
+      "name": {
+        "description": "Name of the location, e.g. \"Office\", \"Home\".",
+        "minLength": 1,
+        "type": "string"
+      },
+      "notifyUser": {
+        "description": "Who to remind: user ID, email, name, or \"me\". Must collaborate on the task's project. Defaults to the creator.",
+        "type": "string"
+      },
+      "radius": {
+        "description": "Radius in meters for the geofence. Defaults to server default.",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "taskId": {
+        "description": "The ID of the task to set a reminder for.",
+        "minLength": 1,
+        "type": "string"
+      },
+      "type": {
+        "const": "location",
+        "type": "string"
+      }
+    },
+    "required": [
+      "type",
+      "taskId",
+      "name",
+      "locLat",
+      "locLong",
+      "locTrigger"
+    ],
+    "type": "object"
+  }
+]

addedOutput schema / properties / reminders / items / properties / notifyUid

Added value: +{
+  "description": "User ID the reminder notifies.",
+  "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"

Changed15 schema fields changedv12.5.3Aug 7, 2026
- changedOutput schema / properties / reminders / items / properties / due / description
```
Previous value: -"Due date info (absolute and sometimes relative reminders)."New value: +"Absolute, and sometimes relative, reminders."
```
- changedOutput schema / properties / reminders / items / properties / due / properties / date / description
```
Previous value: -"Due date in ISO format."New value: +"ISO 8601."
```
- changedOutput schema / properties / reminders / items / properties / due / properties / datetime / description
```
Previous value: -"Due datetime in ISO format."New value: +"ISO 8601."
```
- removedOutput schema / properties / reminders / items / properties / due / properties / isRecurring / description
```
Removed value: -"Whether this is a recurring reminder."
```
- removedOutput schema / properties / reminders / items / properties / due / properties / timezone / description
```
Removed value: -"Timezone of the reminder."
```
- removedOutput schema / properties / reminders / items / properties / id / description
```
Removed value: -"The unique ID of the reminder."
```
- changedOutput schema / properties / reminders / items / properties / isUrgent / description
```
Previous value: -"Whether this is an urgent reminder (relative and absolute reminders only)."New value: +"Relative and absolute reminders only."
```
- changedOutput schema / properties / reminders / items / properties / locLat / description
```
Previous value: -"Latitude (location reminders only)."New value: +"Location reminders only."
```
- changedOutput schema / properties / reminders / items / properties / locLong / description
```
Previous value: -"Longitude (location reminders only)."New value: +"Location reminders only."
```
- changedOutput schema / properties / reminders / items / properties / locTrigger / description
```
Previous value: -"Trigger type: on_enter or on_leave (location reminders only)."New value: +"Location reminders only."
```
- changedOutput schema / properties / reminders / items / properties / minuteOffset / description
```
Previous value: -"Minutes before due time to trigger (relative reminders only)."New value: +"Minutes before due. Relative reminders only."
```
- changedOutput schema / properties / reminders / items / properties / name / description
```
Previous value: -"Location name (location reminders only)."New value: +"Location name. Location reminders only."
```
- changedOutput schema / properties / reminders / items / properties / radius / description
```
Previous value: -"Geofence radius in meters (location reminders only)."New value: +"Geofence radius in metres. Location reminders only."
```
- removedOutput schema / properties / reminders / items / properties / taskId / description
```
Removed value: -"The task ID this reminder belongs to."
```
- removedOutput schema / properties / reminders / items / properties / type / description
```
Removed value: -"The type of reminder: relative, absolute, or location."
```
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 readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral default — reminders notify their creator unless notifyUser says otherwise — but says nothing about duplicate handling or whether re-adding the same reminder is safe, which matters given idempotentHint=false.

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?

Three tight sentences, front-loaded with the action and the type taxonomy, then the taskId requirement, then the recipient default. Nothing is wasted and no sentence repeats another.

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?

With an output schema, full annotation coverage, and a rich oneOf schema, the description supplies what structured fields cannot: the type taxonomy framing and the default recipient rule. The remaining gap is routing relative to update-reminders, which the sibling list makes relevant.

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 taskId, minuteOffset, due, locLat/locLong, service, etc. The description only restates the type taxonomy at a high level ("relative" minutes before due, "absolute" specific date/time, "location" geofence), adding framing but no field-level detail beyond the schema.

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 opens with a specific verb+resource ("Add reminders to tasks") and enumerates the three supported reminder types, so an agent knows exactly what the tool produces. It does not, however, differentiate itself from the sibling update-reminders or find-reminders, which keeps it short of a 5.

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?

"Each reminder must specify a taskId" and the type breakdown imply when the tool applies (creating new reminders on existing tasks), but there is no explicit guidance on when to use this versus update-reminders/find-reminders, nor any stated prerequisites such as collaboration on the task's project.

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