This server connects a local MCP client (like Claude) to Microsoft To Do, letting you sign in and manage tasks and folders conversationally.
Authentication: login (start or finish OAuth with a pasted callback URL), logout, login_status
Provider info: list_providers shows connected provider status and capabilities
Task lists: list_task_lists, create_task_list, delete_task_list
Task browsing: list_tasks (single list or aggregate across all, with pagination and completed filter), get_task, search_tasks (substring across all lists)
Task management: create_task (title, notes, due date, subtask nesting), update_task (partial update, clear due date, mark completed/needsAction), complete_task, delete_task
Organization: move_task_between_lists (recreates in target list, deletes original)
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mstodo-bridge Add a task to my To Do list to submit the report by Friday"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Manage Microsoft To Do directly in Claude. An MCP server with zero-configuration setup; sign-in happens right in the conversation.
claude mcp add -s user taskbridge -- npx -y mstodo-bridge-s user applies globally (available in all projects). Restart your Claude Code session after finishing.
Claude Desktop: edit the config file (Windows %APPDATA%\Claude\claude_desktop_config.json, macOS ~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"taskbridge": {
"command": "npx",
"args": ["-y", "mstodo-bridge"]
}
}
}Cursor / other MCP clients: add it the same way with npx -y mstodo-bridge as the stdio command. Save and restart the client.
It does not need to be attached to a client; it can also run standalone as a service with an admin console:
npx mstodo-bridge --http # 管理台 http://127.0.0.1:46377/adminOn first launch it prints an admin password and an MCP Bearer token (shown only once). Other clients can then connect remotely via http://<host>:46377/mcp (Bearer auth); see "Deployment" below for deploying to a server / Hugging Face Spaces.
Related MCP server: Remote MCP Entra ID Todo
After restarting the client, just tell Claude:
Help me connect to Microsoft To Do
Claude will call the login tool and give you an authorization link → open it in a browser → consent with your Microsoft personal account → it automatically reconnects and completes. After that you can operate in natural language:
Show my lists · Add X to "Research & Academics", due Friday · Search tasks containing "paper" · Complete item 3
npx mstodo-bridge --http --openOpen the admin console in a browser and sign in with the admin password printed at startup;
On the Microsoft To Do card, click "Connect account"; after completing authorization in the browser, it automatically redirects back;
In remote environments (browser and server are not on the same machine), after authorization it will jump to localhost and show an error — this is expected; just paste the full URL from the address bar into the "Complete connection" input box on the card.
Both methods produce exactly the same credentials (~/.mstodo-bridge), so feel free to mix them.
Account & sign-in
Tool | Parameters | Description |
|
| One tool to complete the entire sign-in flow: no argument = start, returns an authorization link and user-facing instructions (including local callback listening); with the user-pasted URL from the address bar = finish the exchange (remote scenario) |
| — | Disconnect account: removes local tokens and any in-progress sign-in (Microsoft-side authorization must be revoked at account.microsoft.com) |
| — | Whether connected, whether sign-in is in progress, and seconds remaining |
| — | List providers with their connection status and capability declarations |
Lists
Tool | Parameters | Description |
|
| List all lists |
|
| Create a new list |
|
| Delete a list and its tasks (not recoverable) |
Task reading
Tool | Parameters | Description |
|
| List tasks; omit |
|
| Get a single task's details |
|
| Search title and notes by substring across lists |
Task writing
Tool | Parameters | Description |
|
| Create; |
|
| Partial update; |
|
| Mark as complete |
|
| Delete a task |
|
| Move between lists (recreates the item in the target list, then deletes the source task) |
Parameters marked with
provider?can be omitted in single-account mode.
PORT=7860 HOST=0.0.0.0 PUBLIC_BASE_URL=https://<user>-<space>.hf.space npx mstodo-bridge --httpEnvironment variable / flag | Description |
| Admin console password (auto-generated if missing) |
| Public base URL; determines how the authorization callback is displayed and redirected |
| Outbound proxy (http/https only; for SOCKS, use your proxy software's mixed port) |
| Override the built-in OAuth client ID |
| Credentials directory (default |
| Listening port (default 46377; use |
Credentials are kept only locally (~/.mstodo-bridge, permissions 0600); passwords and tokens are stored only as scrypt hashes with constant-time comparison; OAuth uses PKCE plus a one-time state throughout; the admin console has strict CSP and login rate limiting. When a refresh token becomes invalid, it is automatically cleared and you are guided to reconnect.
git clone https://github.com/WNJXYK/MSTodo-Bridge && cd MSTodo-Bridge
npm install && npm run build && npm testIssues and PRs are welcome at GitHub.
Mark a task completed.
| Name | Required | Description | Default |
|---|---|---|---|
| listId | Yes | ||
| taskId | Yes | ||
| provider | No | Provider id (mstodo). Omit when exactly one provider is connected. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but does not reveal side effects, irreversibility, permission needs, or behavior for already-completed tasks. The mutation is implied but not contextualized.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words and the action is front-loaded. While appropriately structured, it is too sparse to fully inform the agent, so it does not earn a top score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations, no output schema, and two undocumented required parameters, the description is incomplete. It does not clarify how listId and taskId are used or what happens after completion, leaving an agent without essential operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 33%, with only the provider parameter described. The description 'Mark a task completed' adds no meaning for the required listId and taskId parameters, failing to explain their roles or relationship, and thus does not compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Mark a task completed' uses a specific verb and resource, clearly indicating the operation changes a task's status to completed. It is distinguishable from sibling tools like create_task, update_task, and delete_task by its unique completion outcome, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus update_task or move_task_between_lists, and it mentions no prerequisites or exclusions. The intended use case is only implied by the tool name and terse description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a task. dueDate accepts ISO date (2026-08-25) or RFC 3339 datetime. parentTaskId nests it as a subtask where supported.
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | ||
| title | Yes | ||
| listId | No | Omit for the provider default list | |
| dueDate | No | ||
| provider | No | Provider id (mstodo). Omit when exactly one provider is connected. | |
| parentTaskId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full behavioral burden. It usefully discloses accepted date/datetime formats and the conditional subtask nesting behavior, but it says nothing about side effects, provider requirements, failure modes, or default list behavior. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences front-load the operation and then provide the two non-obvious parameter behaviors. There is no filler or repetition of schema boilerplate, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With six parameters, no annotations, and no output schema, the description is incomplete. It omits invocation context for listId/provider, default-list behavior, and what the tool returns or does on failure. The agent can invoke it in simple cases but lacks enough context to handle ambiguous or provider-specific situations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, so the description must compensate. It adds real meaning for dueDate by specifying accepted ISO/RFC 3339 formats and for parentTaskId by explaining nesting. However, notes and title are left undocumented in prose, and listId/provider are only covered by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific verb-resource pair 'Create a task,' which is unambiguous and immediately conveys the operation. The added dueDate and parentTaskId details sharpen scope, but it does not explicitly differentiate from sibling tools like create_task_list or update_task, so it stops short of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No conditions, prerequisites, or alternatives are given. It never states when to choose create_task over update_task or complete_task, and it does not explain how to handle the listId or provider selection. The 'where supported' phrase hints at a limitation but leaves the agent without guidance for unsupported cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new task list (folder).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| provider | No | Provider id (mstodo). Omit when exactly one provider is connected. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states only that a task list is created, but does not mention permissions, provider handling, duplicate-name behavior, persistence effects, or any side effects. This is a meaningful gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single direct sentence with no filler words, and the parenthetical '(folder)' adds a useful synonym. It is front-loaded and easy to parse, though it is brief enough that it sacrifices useful context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters, no annotations, and no output schema, this description is incomplete. It does not convey how the optional provider should be used, what the result of creation is, or how this operation fits with sibling list-management tools. The schema partially covers provider, but the overall tool definition leaves important gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%: the name parameter has no schema description, and provider has one. The tool description adds no parameter-level meaning beyond the phrase 'task list (folder)', which only weakly hints that name is the folder title. It does not explain the provider parameter's behavior or optionality semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Create a new task list', with a clarifying parenthetical '(folder)'. This is enough to distinguish it from sibling tools like create_task or delete_task_list, though it does not explicitly name the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied: an agent can reasonably infer this tool is for creating a task list. However, there is no explicit guidance about when to prefer this over alternatives, or any conditions around provider selection such as omitting provider when only one is connected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a task permanently.
| Name | Required | Description | Default |
|---|---|---|---|
| listId | Yes | ||
| taskId | Yes | ||
| provider | No | Provider id (mstodo). Omit when exactly one provider is connected. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. 'Permanently' usefully signals that deletion is irreversible, but it does not disclose side effects, failure behavior, or whether dependent data is removed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single five-word sentence that is front-loaded and contains no filler. Every word earns its place by stating the action and its permanence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no annotations and no output schema, the description is too sparse. It omits important operational context such as prerequisites, recovery options, and what happens to related items.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, and the description adds no parameter-level detail. An agent must infer that taskId identifies the task and listId scopes the deletion; the required parameters are not otherwise explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the specific action ('Delete'), the resource ('a task'), and the adverb 'permanently' makes the operation's intent clear. This distinguishes it from sibling tools like complete_task or delete_task_list without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to prefer this tool over alternatives, no exclusions, and no mention of prerequisites. The sentence states what it does, not when to select it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an entire task list and its tasks. Irreversible.
| Name | Required | Description | Default |
|---|---|---|---|
| listId | Yes | ||
| provider | No | Provider id (mstodo). Omit when exactly one provider is connected. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explicitly states 'Irreversible' and that the operation deletes 'its tasks', revealing the permanent, cascading nature of the action. This is meaningful context, though it omits permission requirements and response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and target, with 'Irreversible' as a separate high-impact warning. Every word earns its place and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The definition covers the core destructive behavior and irreversibility, and the schema documents the provider parameter. However, it lacks guidance on how to obtain valid listId values and does not situate the tool relative to delete_task or move_task_between_lists. For low complexity and no output schema, this is a moderate gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%: the required listId has no description in the schema, and the tool description does not compensate. Provider is documented, but listId's format, meaning, and source are never explained. The description adds no parameter-level semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('Delete') with a clear resource ('entire task list and its tasks'), which distinguishes it from sibling delete_task (single task). It also communicates the cascade scope, making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when wanting to delete a whole list, but it provides no explicit guidance on when to use this tool versus delete_task or move_task_between_lists. It also does not state exclusions or prerequisites, so usage context is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one task by list and task id.
| Name | Required | Description | Default |
|---|---|---|---|
| listId | Yes | ||
| taskId | Yes | ||
| provider | No | Provider id (mstodo). Omit when exactly one provider is connected. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure, but it only states the basic fetch action. It does not mention read-only behavior, not-found errors, provider resolution, or whether the full task object 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler, making it easy to parse. However, its brevity comes at the cost of omitting useful context that could be included without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description omits usage conditions, provider handling, and error/return behavior. For a tool with no annotations and no output schema, more context is needed to call it reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%; listId and taskId have no schema descriptions. The description clarifies that these two parameters are the lookup keys, but it does not explain the optional provider parameter or provide type/format details, leaving a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and defines the target as a single task identified by list and task ID, clearly distinguishing it from sibling tools like list_tasks and search_tasks. There is no ambiguity about what operation is performed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as list_tasks or search_tasks. The description merely states the action and leaves tool selection to inference, with no mention of prerequisites or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the Microsoft To Do provider and its auth state and capabilities. Run this first to learn what is available.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'Show' reasonably implies a read-only operation, but the description does not explicitly state that it has no side effects or whether authentication is required before calling it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The first sentence states the core function, and the second provides practical usage guidance, making it well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter discovery tool with no output schema, the description names the key outputs: the provider, auth state, and capabilities. It could be slightly more complete by noting whether this call is safe before login, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially complete at 100% coverage. The description appropriately focuses on behavior and output rather than parameters, which is the correct baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Show the Microsoft To Do provider and its auth state and capabilities.' It clearly communicates what the tool does, though it does not explicitly differentiate itself from sibling tools like login_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Run this first to learn what is available' gives explicit usage timing and context. It does not name alternatives or state when not to use it, but the instruction to run first is clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the task lists (folders) of a provider.
| Name | Required | Description | Default |
|---|---|---|---|
| provider | No | Provider id (mstodo). Omit when exactly one provider is connected. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden; 'List' indicates a read-only operation, which is the main behavioral trait. It adds a helpful clarification that these are folders, but it does not disclose any behavior around multiple providers, empty results, or errors. Still, for a simple listing tool this is minimally adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence with no filler; the parenthetical '(folders)' earns its place by clarifying terminology. The description is front-loaded and entirely relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter, no output schema, and no nested objects, the description plus schema cover the essential calling context. A minor gap is that the return shape is not described, but 'list' makes the result type obvious.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter provider is already fully documented in the input schema, including an example value and the conditional omit guidance. The description adds no new parameter semantics, so the baseline of 3 for full schema coverage applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific action ('List') and resource ('task lists (folders) of a provider'), which clearly separates it from task-level siblings like list_tasks and from create_task_list/delete_task_list. It doesn't explicitly name a sibling, but the resource scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The use case is implied by the phrasing (list task lists for a provider), and the input schema adds the key condition that the provider parameter should be omitted only when exactly one provider is connected. However, the description does not explicitly state when to prefer this tool over alternatives or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tasks. Give listId for one list; omit it to page across every list of the provider.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | Pagination cursor from a previous call (single-list mode only) | |
| listId | No | Omit to aggregate across all lists | |
| provider | No | Provider id (mstodo). Omit when exactly one provider is connected. | |
| includeCompleted | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It usefully reveals that omitting listId aggregates across all lists and that pagination is involved, but it does not describe auth requirements, ordering, return shape, or how includeCompleted affects results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two brief sentences carry the essential scoping and pagination behavior with no filler. The instruction is front-loaded and immediately actionable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main listId/pagination behavior but lacks guidance for choosing this tool over search_tasks, and with no output schema it does not clarify expected return fields. Given multiple siblings and four parameters, this is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, so the schema already documents most parameters. The description adds meaningful context for listId ('one list' vs 'page across every list'), but it does not add semantic detail for cursor, provider, or includeCompleted beyond what the schema already says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The verb 'List' and resource 'tasks' are clear, and the description adds specific scope behavior ('listId for one list; omit it to page across every list'). However, it does not explicitly differentiate from the sibling search_tasks, which also retrieves tasks in a filtered way.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a direct usage instruction for the listId parameter and when to omit it. It does not, however, state when to use this tool versus search_tasks or other task-related siblings, leaving the choice partially implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connect Microsoft To Do. Call WITHOUT arguments to start: it returns an authorize URL for the user to open and consent, plus a ready-to-relay message covering the paste-back fallback. When the user later sends you a localhost callback URL from their address bar, call login AGAIN passing it as callbackUrl to finish.
| Name | Required | Description | Default |
|---|---|---|---|
| callbackUrl | No | 用户粘贴的授权后地址栏完整 URL(含 code 与 state)。传此参数=完成登录;不传=开始登录 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the first call returns an authorize URL and a ready-to-relay message, and that the second call finishes login with the callbackUrl. It does not describe side effects like token storage or error states, but the core behavior is transparent enough for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences front-load the purpose and then specify the exact two call patterns. Every clause contributes necessary information; there is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers both invocation phases and the callback fallback, which is the bulk of what an agent needs to drive this OAuth login flow. It does not mention what the final successful response looks like, but given there is no output schema, a bit more detail there would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes callbackUrl. The description adds valuable context by explaining that omitting the parameter starts login and passing it finishes login, reinforcing the two-phase flow beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Connect Microsoft To Do' and explains the two-phase login flow (start with no arguments, finish with callbackUrl). This distinguishes it from siblings like logout and login_status without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use instructions: call without arguments to initiate login, and call again with the callbackUrl when the user provides it. It does not explicitly mention alternatives or when not to use it, but the two-step flow is clearly specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether Microsoft To Do is connected. Use before task tools; if not connected, call login.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states the core behavior (checking connection status) and implies it is non-mutating by directing unconnected users to call login separately. However, it does not describe the return value format, whether the result is a simple boolean, or any potential side effects, which leaves some behavioral uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero wasted words. The first sentence states the core purpose, and the second adds usage timing and the alternative action, front-loading the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, simple status-checking tool, the description covers the when and the conditional next step. The only gap is the absence of explicit return-value documentation, but the description's conditional language implies the output is testable enough for an agent to act on.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and schema description coverage is 100%, so there are no parameter semantics to explain. Per the rubric, a baseline of 4 is appropriate for tools with no parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Check') and a clear resource ('whether Microsoft To Do is connected'), which precisely distinguishes it from sibling tools like login and logout. It clearly establishes itself as a status/readiness check for the task tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Use before task tools' explicitly tells the agent when to invoke this tool. The follow-up 'if not connected, call login' provides a clear conditional branch and names the alternative tool, leaving no ambiguity about subsequent actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Disconnect Microsoft To Do: deletes the locally stored tokens (and any pending login). The Microsoft-side app consent is NOT revoked; to fully revoke, remove the app at account.microsoft.com > Privacy.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so excellently. It discloses that local tokens are deleted, pending logins are cleared, and that Microsoft-side app consent is NOT revoked. It also explains the external follow-up required for full revocation, which is critical behavioral context beyond merely saying 'logout.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two focused sentences with no filler. The main action and side effect are front-loaded, and the important consent-revocation caveat is appended clearly. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter logout tool, the description is complete. It covers what happens locally, what does not happen on the Microsoft side, and where to go for full revocation. No output schema is present, but none is needed for this action, and no behavioral expectations are left unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty input schema, so there is nothing for the description to clarify. The baseline of 4 is appropriate because no parameter explanation is needed and the description adds no irrelevant parameter detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Disconnect Microsoft To Do' and explains the concrete action ('deletes the locally stored tokens (and any pending login)'). This clearly differentiates it from sibling login/login_status tools by describing the local disconnect behavior rather than authentication or status checking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the intended use obvious: call this to disconnect the local Microsoft To Do session. It also provides an explicit alternative and condition for when not to rely on this tool: 'to fully revoke, remove the app at account.microsoft.com > Privacy.' This gives clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recreate an existing task in another list and delete it from the source list (Graph To Do has no native move). Use to reorganize.
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | ||
| provider | No | Provider id (mstodo). Omit when exactly one provider is connected. | |
| toListId | Yes | Destination list | |
| fromListId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the destructive step ('delete it from the source list') and explains why the operation is structured this way. However, it does not warn that recreation likely produces a new task ID or may lose metadata, which is an important behavioral consequence for an agent to know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with no wasted words. The core behavior is front-loaded, and the parenthetical rationale adds important context without bloating the description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the underlying recreate+delete mechanism and the general purpose, which is helpful. However, it omits critical operational details such as non-atomicity, possible duplicate tasks if deletion fails, and whether the recreated task keeps all original properties. With no output schema, these gaps are not filled elsewhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents 'provider' and 'toListId', but leaves 'taskId' and 'fromListId' undocumented. The description adds meaning by mapping 'existing task' to taskId, 'another list' to toListId, and 'source list' to fromListId, compensating for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource combination: it recreates an existing task in another list and deletes it from the source list. It also explains the reason (Graph To Do has no native move), which clearly distinguishes this tool from create_task and delete_task siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a general use case ('Use to reorganize') and implies it should be used when moving tasks between lists, but it does not explicitly state when not to use it or name alternatives. The lack of explicit routing to/from sibling tools leaves some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search open tasks by substring across every list of every connected provider.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| provider | No | Provider id (mstodo). Omit when exactly one provider is connected. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It discloses that only open tasks are searched, that matching is by substring, and that scope spans all lists and providers. This is sufficient to infer a read-only search operation, though it does not detail field-level matching or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense, front-loaded sentence with no filler. Every part contributes: what is searched, the matching mode, and the scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequately complete for a two-parameter search tool with no output schema. It explains the query's role, the provider optionality is handled by the schema, and the scope is explicit. Minor omissions like exact fields matched or result limits are not critical to correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: provider is described but query is not. The description adds meaning to query by framing it as a substring used to search open tasks. Provider semantics are already covered in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') and identifies the resource ('open tasks') with a clear scope ('across every list of every connected provider'). It clearly distinguishes this from siblings like list_tasks or get_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description communicates when to use the tool: when a global substring search across all connected providers is needed. It does not explicitly name alternatives or state when not to use it, but the 'across every list of every connected provider' phrasing provides clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a task (partial). Set status "completed" or "needsAction", change title/notes, or set dueDate (null removes it).
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | ||
| title | No | ||
| listId | Yes | ||
| status | No | ||
| taskId | Yes | ||
| dueDate | No | ||
| provider | No | Provider id (mstodo). Omit when exactly one provider is connected. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It usefully reveals that updates are partial and that null removes dueDate. It does not disclose side effects, required identifiers' roles, permissions, idempotency, or what the response contains, which leaves meaningful behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One tight sentence packs the core action, supported fields, allowed status values, and the dueDate-null caveat. It is front-loaded and every phrase adds value with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 7 parameters, no output schema, and no annotations, so the description is the only source of guidance. It covers the main fields but omits success/error behavior, provider disambiguation, required-parameter semantics, and how this relates to overlapping siblings like complete_task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 14%, so the description must compensate. It adds meaning for status ('completed'/'needsAction'), title, notes, and dueDate null semantics. It does not clarify that listId and taskId are identifiers or explain the provider parameter beyond what the schema already says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Update'), the resource ('a task'), and the partial-update scope, and enumerates exactly which fields can be changed. It is distinguishable from create/get/delete siblings, though it does not explicitly address the overlap with complete_task, which may also set status to completed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by the field list: use this when updating status, title, notes, or dueDate. However, there is no explicit guidance on when not to use it, such as 'use complete_task for simple completion' or 'use move_task_between_lists to change the list.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.4.0complete_taskcreate_taskcreate_task_listdelete_taskdelete_task_listget_tasklist_providerslist_task_listslist_tasksloginlogin_statuslogoutmove_task_between_listssearch_tasksupdate_taskScored across 15 tools
Most tools target distinct resources and actions, but there are overlapping boundaries: update_task can mark a task completed, making complete_task redundant, and login_status overlaps with list_providers for checking auth state. Descriptions help clarify intended use, but an agent could still struggle to choose between these pairs.
Task and list tools consistently follow a verb_noun pattern: list_tasks, create_task, delete_task_list, move_task_between_lists. The auth tools (login, login_status, logout) deviate from that pattern, but they form their own predictable auth-related group, so the overall naming is mostly consistent.
Fifteen tools is on the upper end of the ideal range but is reasonable for a Microsoft To Do bridge covering auth, providers, task lists, and individual tasks. A few tools like complete_task and list_providers feel somewhat redundant, suggesting the count could be trimmed slightly, but it is not excessive.
The server covers the core lifecycle well: list, create, get, update, complete, delete, search, and move tasks, plus list and auth management. Minor gaps exist, such as no way to rename a task list and no dedicated get_task_list operation, but agents can work around these with the available tools.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Create, list, and complete todo items through MCP.
Official Todoist MCP server for AI assistants to manage tasks, projects, and workflows.
