Todoist AI MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

find-reminders

Read-onlyIdempotent

Retrieve all time-based and location reminders for a Todoist task, or fetch a specific reminder by ID to view its details.

Instructions

Find reminders by task ID (returns all reminder types), or get a specific reminder by its ID. Use reminderId for time-based reminders and locationReminderId for location reminders.

Input Schema

Name	Required	Description
`taskId`	No	Find all reminders for a specific task. Returns both time-based and location reminders.
`reminderId`	No	Get a specific time-based reminder (relative or absolute) by its ID.
`locationReminderId`	No	Get a specific location reminder by its ID.

Output Schema

Name	Required	Description
`searchId`	Yes	The ID used for the search.
`reminders`	Yes	The found reminders (time-based and location).
`searchType`	Yes	The search type used: "task", "reminder", or "location_reminder".
`totalCount`	Yes	Total reminders in this response.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv13.7.0Oct 27, 2026
- 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.5/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful fact that a taskId lookup returns both time-based and location reminders, but says nothing about result volume, pagination, or behavior when no reminder matches.

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

Conciseness4/5

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

Two short clauses, front-loaded with the primary taskId use case followed by the single-item modes. No filler; the only mild redundancy is repeating the parameter-level distinctions already in the schema.

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 a full output schema present and 100% parameter description coverage, the description need not explain return values, and it correctly frames the two access patterns. Missing only the mutual exclusivity of the three ID parameters and any empty-result behavior.

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 each parameter already carries its own description that essentially duplicates the description text ('Get a specific time-based reminder ... by its ID'). The description adds no format, prefix, or ID-provenance information beyond the schema, so 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?

States a specific verb (find) and resource (reminders), and enumerates the two lookup modes: by task ID (returning all types) or by a specific reminder ID. It does not name or contrast any sibling (e.g. find-tasks, update-reminders), so it stops short of full differentiation.

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?

The description gives mode-selection guidance (reminderId for time-based, locationReminderId for location), which is real usage direction. But there is no guidance on when to reach for this tool versus add-reminders/update-reminders or find-tasks, and no note that the three parameters are mutually exclusive alternatives.

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