Todoist AI MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

find-projects

Read-onlyIdempotent

List or search the projects you've joined by name; filter by active or archived status, paginate results, and optionally include unjoined workspace projects.

Instructions

List or search by name the projects the user has joined. By default only active projects are returned; use archivedStatus ('archived' or 'all') to include archived projects. When searching or when archivedStatus is 'all', all matching projects are returned (pagination is ignored). Otherwise projects are returned with pagination. Workspace projects the user hasn't joined are left out unless includeUnjoined is set, or a search matches no joined project.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "find-projects"
  }
}

Input Schema

Name	Required	Description
`limit`	No	The maximum number of projects to return.
`cursor`	No	The cursor to get the next page of projects (cursor is obtained from the previous call to this tool, with the same parameters).
`searchText`	No	Search for a project by name (partial and case insensitive match). Supports wildcards (e.g. "work" for prefix match). Use "\" for a literal asterisk. If omitted, all projects are returned.
`archivedStatus`	No	Which projects to return by archive status: 'active' (default, non-archived only), 'archived' (archived only), or 'all' (both active and archived). Each project includes an isArchived field. Archived projects can be deleted via the delete-object tool (type: 'project').
`includeUnjoined`	No	Also list workspace projects the user can join but hasn't, in unjoinedProjects (first page only). They can't be read until joined; join with project-management (action 'join') only when the user asks.

Output Schema

Name	Required	Description
`hasMore`	Yes
`projects`	Yes	The found projects.
`nextCursor`	No
`totalCount`	Yes	The total number of projects in this page.
`appliedFilters`	Yes
`unjoinedHasMore`	No	More matched than limit; narrow with searchText.
`unjoinedProjects`	No	Up to limit. With includeUnjoined, or when a search matched no joined project.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv15.2.0Nov 12, 2026

addedInput schema / properties / includeUnjoined

Added value: +{
+  "description": "Also list workspace projects the user can join but hasn't, in unjoinedProjects (first page only). They can't be read until joined; join with project-management (action 'join') only when the user asks.",
+  "type": "boolean"
+}

addedOutput schema / properties / unjoinedHasMore

Added value: +{
+  "description": "More matched than limit; narrow with searchText.",
+  "type": "boolean"
+}

addedOutput schema / properties / unjoinedProjects

Added value: +{
+  "description": "Up to limit. With includeUnjoined, or when a search matched no joined project.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "type": "string"
+      },
+      "name": {
+        "type": "string"
+      },
+      "url": {
+        "type": "string"
+      },
+      "workspaceId": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "name",
+      "workspaceId",
+      "url"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Changed1 schema field changedv13.10.1Nov 5, 2026
- changedOutput schema / properties / projects / items / properties / viewStyle / description
```
Previous value: -"list, board or calendar."New value: +"list, board, calendar or table."
```

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 / appliedFilters / description
```
Removed value: -"The filters that were applied to the search."
```
- removedOutput schema / properties / hasMore / description
```
Removed value: -"Whether there are more results available."
```
- removedOutput schema / properties / nextCursor / description
```
Removed value: -"Cursor for the next page of results."
```
- 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."
```
First observedv10.4.2Jul 9, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already cover the read-only, idempotent, non-destructive profile, and the description adds genuinely useful non-obvious behavior: default filtering to active projects, and the surprising rule that pagination is ignored when searching or when archivedStatus is 'all'. It also discloses the fallback where a search matching no joined project surfaces unjoined ones. The main remaining gap is that it does not say what happens with limit when pagination is bypassed.

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?

Four sentences, front-loaded with the core purpose, and every sentence carries a distinct behavioral rule with no filler. The final sentence is compound and slightly dense, but nothing is redundant enough to cut.

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

Completeness5/5

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

The tool has five optional parameters, a simple flat schema, and an output schema, so return-shape explanation is unnecessary. The description covers defaults, pagination exceptions, archive scope, and the unjoined fallback, which is everything an agent needs to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema does not: searchText and archivedStatus interact with limit/cursor by disabling pagination, and includeUnjoined only affects the first page. That is real added semantics rather than restatement.

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

Purpose5/5

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

States a specific verb pair and resource ('List or search by name the projects') plus a scope qualifier ('the user has joined'), which immediately separates it from sibling finders such as find-project-collaborators, find-sections, and find-tasks. An agent can identify the tool's job without opening 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 Guidelines4/5

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

Gives concrete conditions for the two non-default modes: archivedStatus for archived inclusion and includeUnjoined for workspace projects not yet joined. It stops short of naming an alternative tool (e.g. the sibling 'search' or 'fetch-object') for a different retrieval path, so it is clear context rather than full when/when-not routing.

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