Todoist MCP Server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.0
Disambiguation5/5
Every tool has a clearly distinct purpose targeting specific resources (tasks, projects, labels, sections) and actions (create, get, list, update, delete, move, complete). No ambiguity exists; for example, create_task vs. quick_add are differentiated by input method, and move_task vs. update_task handle different aspects of task modification.
Naming Consistency5/5
All tools follow a consistent verb_noun pattern (e.g., create_task, list_labels, update_project) with no deviations. The naming is uniform and predictable, making it easy for agents to understand and select tools based on their actions and targets.
Tool Count3/5
With 24 tools, the count is borderline high for a todo management server, potentially feeling heavy. While each tool serves a specific function, the number might overwhelm agents, as typical well-scoped servers have 3-15 tools. However, it's not extreme enough to score lower.
Completeness5/5
The tool set provides complete CRUD/lifecycle coverage for the Todoist domain, including tasks, projects, labels, and sections. It covers all essential operations from creation to deletion, with additional utilities like moving, commenting, and productivity stats, leaving no obvious gaps for agent workflows.
Average 3.1/5 across 24 of 24 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Add a comment' implies a write/mutation operation, it doesn't specify permissions required, whether comments are editable/deletable, rate limits, or what happens on success/failure. This leaves significant behavioral gaps 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's appropriately sized for a simple tool and front-loads the essential information immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
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 and no output schema, the description is insufficiently complete. It doesn't address what the tool returns, error conditions, or behavioral constraints. Given the complexity of a write operation and lack of structured coverage, more context is needed.
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 fully documents both parameters (taskId and content). The description adds no additional parameter information beyond what's in the schema, meeting the baseline for high schema coverage but not providing extra value.
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 clearly states the action ('Add a comment') and target resource ('to a task'), providing specific verb+resource pairing. However, it doesn't distinguish this tool from potential alternatives like 'update_task' which might also allow comment addition, leaving room for sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives. With sibling tools like 'update_task' that might also modify tasks, there's no indication whether this is the preferred method for adding comments or when other tools should be used instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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. 'Create a new label' implies a write operation, but it doesn't disclose permissions required, whether creation is idempotent, rate limits, or what happens on success/failure (e.g., returns label ID). This leaves critical behavioral traits unspecified 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action ('Create a new label'), making it immediately scannable and appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a mutation (create) with no annotations and no output schema, the description is incomplete. It doesn't cover behavioral aspects like permissions or response format, and while the schema handles parameters, the overall context for safe and effective use is lacking. This is inadequate for a tool that modifies system state.
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 fully documents all parameters (name, color, isFavorite) with descriptions. The description adds no parameter-specific information beyond implying a label is created. This meets the baseline of 3 when the schema does the heavy lifting, but no extra value is provided.
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 'Create a new label' clearly states the verb ('create') and resource ('label'), making the purpose immediately understandable. It distinguishes from siblings like 'delete_label' or 'update_label' by specifying creation. However, it doesn't specify what kind of label (e.g., task label, project label) or system context, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives. It doesn't mention prerequisites (e.g., needing a project first), when not to use it (e.g., for existing labels), or direct alternatives like 'update_label' for modifications. The agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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. 'Create a new project' implies a write/mutation operation, but it doesn't describe what happens upon creation (e.g., default settings, success response), potential side effects (e.g., impact on existing projects), or any limitations (e.g., rate limits, authentication requirements). This leaves significant gaps 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly. Every word earns its place by directly stating the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (a mutation tool with 5 parameters) and lack of annotations or output schema, the description is insufficient. It doesn't explain what the tool returns upon success/failure, how it interacts with sibling tools (e.g., 'list_projects' or 'update_project'), or any behavioral nuances. For a creation tool in a project management context, more context is needed.
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%, with all 5 parameters well-documented in the schema itself (e.g., 'name' as required, 'color' with examples, 'viewStyle' with enum values). The description adds no parameter information beyond what's in the schema, so it meets the baseline of 3 for high schema coverage without adding extra value.
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 clearly states the action ('Create') and resource ('new project'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'create_label', 'create_section', or 'create_task', which all follow the same 'create [resource]' pattern without specifying what distinguishes a project from these other entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives. It doesn't mention prerequisites (e.g., permissions needed), when to choose this over similar creation tools (like 'create_task'), or any constraints (e.g., project limits). The agent must infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool creates a section but doesn't mention whether this requires specific permissions, what happens on success/failure (e.g., returns the new section ID), or any side effects (e.g., if it affects project structure). For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the core purpose without unnecessary words. It's appropriately sized for a simple creation tool and front-loads the essential information ('Create a new section within a project'). Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., the new section object or ID), error conditions, or behavioral constraints. For a tool that modifies data, this leaves the agent with insufficient context to use it effectively.
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?
The description adds no parameter information beyond what the schema already provides (100% coverage). The schema fully documents both parameters (projectId and name) with clear descriptions. Since schema coverage is high, the baseline score of 3 is appropriate, as the description doesn't need to compensate but also adds no extra value.
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 clearly states the action ('Create') and resource ('new section within a project'), making the purpose immediately understandable. It distinguishes from sibling tools like 'create_project' or 'create_task' by specifying the section context. However, it doesn't explicitly mention what distinguishes it from 'move_section' or 'update_section' beyond the creation aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives. It doesn't mention prerequisites (e.g., needing an existing project), when not to use it (e.g., for updating instead of creating), or how it relates to siblings like 'list_sections' or 'delete_section'. The agent must infer usage from the name and schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'Create a new task' which implies a write/mutation operation, but doesn't disclose behavioral traits like required permissions, whether the task is immediately visible, error conditions, or what happens with conflicting due date formats. For a mutation tool with zero annotation coverage, this is a significant gap.
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?
Single sentence, front-loaded with the core purpose, efficiently lists key optional fields. No wasted words or redundant information. Every part of the description earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 12 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what the tool returns (e.g., task ID, success status), error handling, or behavioral constraints. The schema covers parameter details, but the description lacks critical operational context.
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 all 12 parameters thoroughly. The description adds minimal value by listing a subset of optional fields (due date, priority, labels, project) but doesn't provide additional context beyond what's in the schema. Baseline 3 is appropriate when the schema does the heavy lifting.
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 clearly states the verb ('Create') and resource ('new task'), and lists optional fields (due date, priority, labels, project). It distinguishes from siblings like 'update_task' or 'complete_task' by focusing on creation, but doesn't explicitly contrast with 'quick_add' which might be a simpler alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'quick_add' (which appears to be a sibling tool) or 'create_task' with minimal vs. full parameter sets. The description mentions optional fields but doesn't provide context on when to include them or prerequisites for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 indicates the operation is destructive ('permanently delete'), which is helpful, but lacks critical details: whether it requires specific permissions, if deletion is reversible, what happens to associated data (e.g., comments or labels), or error conditions (e.g., invalid taskId). For a destructive tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—just three words—and front-loaded with the essential action and resource. There is zero wasted language, making it highly efficient for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature, lack of annotations, and no output schema, the description is incomplete. It doesn't address behavioral aspects like permissions, reversibility, or error handling, which are critical for safe usage. The conciseness comes at the cost of necessary context for a deletion operation.
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?
The schema description coverage is 100%, with the single parameter 'taskId' fully documented in the schema. The description adds no additional parameter information beyond what's in the schema, so it meets the baseline of 3 where the schema does the heavy lifting.
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 clearly states the action ('permanently delete') and resource ('a task'), making the purpose immediately understandable. However, it doesn't differentiate this tool from other deletion tools like delete_label, delete_project, or delete_section, which would require specifying it's specifically for tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives. It doesn't mention prerequisites (e.g., needing the task ID), when not to use it (e.g., for archiving instead), or relationships with sibling tools like get_task (to verify before deletion) or uncomplete_task (as an alternative action).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states what the tool does but provides no information about permissions required, rate limits, response format, whether data is real-time or cached, or any other behavioral characteristics. This is inadequate for a tool that presumably accesses user data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise at just 6 words, front-loading the essential purpose without any unnecessary elaboration. Every word earns its place in communicating the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of productivity statistics (which could include metrics, trends, comparisons) and the absence of both annotations and output schema, the description is insufficient. It doesn't indicate what specific statistics are returned, in what format, or what insights are provided, leaving significant gaps for an AI agent.
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?
The description adds no parameter information beyond what the schema already provides. With 100% schema description coverage and only one parameter with clear enum values and default, the schema does all the work. The baseline score of 3 reflects adequate but unenhanced parameter documentation.
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 clearly states the tool's purpose with a specific verb ('Get') and resource ('task completion statistics and productivity insights'), making it immediately understandable. However, it doesn't explicitly differentiate from potential sibling tools like 'get_task' or 'list_tasks' that might provide related but different data, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives. With multiple sibling tools like 'get_task', 'list_tasks', and various task management tools, there's no indication of when productivity statistics are appropriate versus individual task data or lists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 it's a list operation (implying read-only), but doesn't mention any constraints like pagination, rate limits, authentication requirements, or what happens when projectId is omitted. This is inadequate for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero wasted words. It's front-loaded with the core purpose and appropriately sized for a simple list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete. It doesn't explain what the output looks like (e.g., format, fields), behavioral constraints, or how it differs from siblings. For a tool in this context, more detail is needed to be fully helpful.
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 fully documents the single parameter. The description adds no additional parameter semantics beyond implying the tool lists sections, which aligns with the schema. This meets the baseline for high schema coverage.
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 clearly states the verb ('List') and resource ('sections within a project'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_projects' or 'list_tasks', which would be needed for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description doesn't mention sibling tools like 'list_projects' for broader context or 'get_task' for specific task details, leaving the agent without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but lacks behavioral details. It implies a mutation ('Move') but doesn't disclose permissions needed, whether the move is reversible, effects on related data (e.g., tasks in the section), or error handling. This is inadequate 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's front-loaded with the core action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
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 and no output schema, the description is incomplete. It lacks crucial context like what happens after the move, potential side effects, or return values, leaving significant gaps for an agent to use it correctly.
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 both parameters fully. The description adds no additional meaning beyond implying 'sectionId' is the source and 'projectId' is the destination, which is minimal value over 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 clearly states the action ('Move') and resource ('a section'), specifying the destination ('to a different project'). It distinguishes from siblings like 'move_task' by focusing on sections rather than tasks, but doesn't explicitly contrast them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing valid IDs), exclusions, or comparisons to siblings like 'update_section' or 'create_section' that might handle similar operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the action ('move') but doesn't describe what happens during the move: whether it preserves task metadata, how it handles conflicts, if it requires specific permissions, or what the response looks like. For a mutation tool with zero annotation coverage, this leaves significant behavioral gaps unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('move a task') followed by the three destination options. Every word earns its place with zero redundancy or unnecessary elaboration. It's appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
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 and no output schema, the description is incomplete. It doesn't address behavioral aspects like permissions, side effects, error conditions, or response format. While the schema covers parameters well, the overall context for safe and effective tool invocation lacks sufficient guidance.
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%, with all four parameters clearly documented in the schema. The description adds minimal value beyond the schema by implying these parameters correspond to the three move options mentioned. However, it doesn't explain parameter relationships (e.g., that projectId, sectionId, and parentId are mutually exclusive options) or provide additional semantic context.
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 clearly states the verb 'move' and resource 'task', specifying three possible destinations: different project, different section, or as a subtask. It distinguishes from obvious siblings like 'create_task' or 'update_task' by focusing on relocation rather than creation or modification of task content. However, it doesn't explicitly differentiate from 'move_section' (which moves sections, not tasks).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives. It doesn't mention prerequisites (e.g., task must exist), constraints (e.g., cannot move to archived projects), or relationships with sibling tools like 'update_task' (which might also handle task properties). There's no explicit 'when-not' or alternative tool recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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. While 'reopen' implies a mutation (changing task status), the description doesn't specify permissions needed, side effects, error conditions, or what happens to task metadata. For a mutation tool with zero annotation coverage, this leaves significant 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it immediately scannable and perfectly concise for this simple operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what 'reopen' means operationally (e.g., sets status to incomplete), what gets returned, or error scenarios. The agent lacks critical context for safe and effective use.
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%, with the single parameter 'taskId' clearly documented in the schema. The description adds no additional parameter context beyond what the schema provides (e.g., format examples, where to find task IDs). Baseline 3 is appropriate when the schema does all the work.
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 clearly states the action ('reopen') and resource ('a completed task'), making the purpose immediately understandable. It distinguishes from siblings like 'complete_task' by specifying the opposite action. However, it doesn't explicitly mention that this is for tasks that were previously completed, which would make it a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives. It doesn't mention prerequisites (e.g., task must be completed), exclusions, or relationships to sibling tools like 'complete_task' or 'update_task'. The agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 this is an update operation (implying mutation), but doesn't cover critical aspects like required permissions, whether changes are reversible, error conditions (e.g., invalid labelId), or what the response contains. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose and enumerates the modifiable fields without unnecessary words. Every element serves a purpose: the verb, resource, and specific attributes. There's no redundancy or wasted space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with no annotations and no output schema, the description is insufficiently complete. It doesn't address behavioral aspects like side effects, error handling, or response format. While the schema covers parameters well, the overall context for safe and effective use is lacking, especially compared to sibling tools that might have similar gaps.
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 fully documents all 5 parameters. The description lists the updatable fields (name, color, favorite status, order) which aligns with the schema but doesn't add meaningful semantic context beyond what's already in the parameter descriptions. The baseline score of 3 reflects adequate but minimal value addition over the comprehensive 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 clearly states the action ('Update') and resource ('an existing label'), and specifies the fields that can be modified (name, color, favorite status, order). It distinguishes from sibling tools like 'create_label' and 'delete_label' by focusing on modification rather than creation or deletion. However, it doesn't explicitly differentiate from other update tools like 'update_project' or 'update_task' beyond the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives. It doesn't mention prerequisites (e.g., needing an existing label ID), when not to use it (e.g., for creating new labels), or how it differs from similar update operations on other resources. The agent must infer usage from the tool name and context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states this is an update operation but doesn't disclose behavioral traits like required permissions, whether changes are reversible, error conditions, or what happens to unspecified fields. For a mutation tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose and enumerates the modifiable fields without unnecessary words. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't cover behavioral aspects like permissions, side effects, or response format. The schema handles parameters well, but overall context for safe and effective use is lacking.
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 all 5 parameters thoroughly. The description lists the updatable fields (name, color, favorite status, view style), which aligns with the schema but doesn't add meaningful semantics beyond what the schema provides. Baseline 3 is appropriate when schema does the heavy lifting.
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 clearly states the action ('Update') and resource ('an existing project'), and specifies the fields that can be modified (name, color, favorite status, view style). It distinguishes from siblings like 'create_project' by focusing on updates, but doesn't explicitly differentiate from other update tools like 'update_label' or 'update_task'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives. It doesn't mention prerequisites (e.g., needing an existing project ID), when not to use it, or how it differs from other update tools in the sibling list like 'update_label' or 'update_task'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 states 'update' implying mutation, but doesn't disclose behavioral traits such as required permissions, whether changes are reversible, error handling, or response format. The description adds minimal context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste. It's front-loaded with the core action and specifies the updatable aspects directly, making it appropriately sized and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutation with 3 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like side effects, permissions, or return values, leaving significant gaps for an AI agent to understand the tool fully.
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 all parameters (sectionId, name, collapsed). The description adds marginal value by mentioning 'rename or collapse/expand', which aligns with the parameters but doesn't provide additional syntax or format details beyond what the schema specifies.
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 clearly states the verb 'update' and resource 'section', specifying what can be updated: 'rename or collapse/expand'. It distinguishes from siblings like 'create_section' or 'delete_section' by focusing on modification, though it doesn't explicitly differentiate from 'move_section' which also modifies sections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives is provided. It doesn't mention prerequisites (e.g., needing an existing section), exclusions (e.g., not for creating or deleting), or compare to siblings like 'move_section' for different update types. The description implies usage for modifying sections but lacks explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. While 'Update' implies mutation, the description doesn't specify whether this requires specific permissions, if changes are reversible, what happens to fields not mentioned (e.g., partial vs. full updates), or error conditions. It mentions fields but lacks behavioral context like rate limits or side effects.
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?
The description is a single, efficient sentence that front-loads the core purpose. It wastes no words but could be slightly more structured (e.g., clarifying it's a partial update). For a tool with 10 parameters, it's appropriately concise given the rich schema documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 10 parameters, no annotations, and no output schema, the description is inadequate. It doesn't cover behavioral aspects (permissions, reversibility), output format, error handling, or usage guidelines. The schema handles parameter documentation well, but the description fails to compensate for missing context on how the tool behaves in practice.
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%, with each parameter well-documented in the schema (e.g., taskId as 'The task ID to update', priority with min/max values). The description adds minimal value beyond the schema by listing example fields (content, due date, priority, labels) but doesn't explain parameter interactions (e.g., dueString vs. dueDate vs. dueDatetime) or provide additional semantic context.
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 clearly states the action ('Update') and resource ('an existing task'), and lists specific fields that can be modified (content, due date, priority, labels, etc.). It distinguishes from sibling tools like 'create_task' by specifying it updates existing tasks, but doesn't explicitly differentiate from other update tools like 'update_label' or 'update_project'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives. It doesn't mention prerequisites (e.g., needing a valid taskId), when to choose this over other task operations like 'complete_task' or 'move_task', or any constraints on usage. The agent must infer usage from the tool name and parameter schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 mentions 'detailed information' but doesn't disclose behavioral traits like whether it's read-only, requires authentication, has rate limits, or what happens if the task ID is invalid. This is a significant gap for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose with no wasted words. Every part earns its place by specifying the action, resource, and included details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a simple input schema, the description is adequate but incomplete. It covers the basic purpose but lacks behavioral context and usage guidelines, making it minimally viable but with clear gaps for a read operation tool.
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 fully documents both parameters. The description adds minimal value by implying 'comments' relate to 'includeComments', but doesn't provide additional syntax or format details beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.
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 clearly states the verb 'get' and resource 'task' with specific details 'including comments and subtasks', making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'list_tasks' or 'update_task', which would require 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 Guidelines2/5
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 alternatives like 'list_tasks' for multiple tasks or 'update_task' for modifications. It lacks context about prerequisites or exclusions, leaving usage decisions to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 the tool lists labels but offers no information about output format, pagination, sorting, rate limits, authentication requirements, or error conditions. For a read operation with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('List all labels'). There is no wasted verbiage, repetition, or unnecessary detail, making it highly concise and well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete for a tool that likely returns a list of labels. It doesn't explain what data is returned (e.g., label names, IDs, colors), the response structure, or any limitations (e.g., maximum labels returned). For a read operation with no structured output documentation, the description should provide more context about the return values.
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?
The input schema has 0 parameters with 100% coverage, meaning no parameters are documented in the schema. The description doesn't mention any parameters, which is appropriate since none exist. It implies the tool operates without inputs, adding value by clarifying it lists 'all' labels without filtering. Baseline 4 is correct for zero-parameter tools.
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 clearly states the action ('List') and resource ('all labels in the Todoist account'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'list_projects' or 'list_tasks', but the specificity of 'labels' provides inherent distinction. The description avoids tautology by not merely restating the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives. It doesn't mention prerequisites (e.g., authentication), contrast with other list tools (like 'list_projects'), or indicate when it might be preferred over other label-related tools (e.g., 'create_label' or 'update_label'). The agent must infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 is 'permanently delete,' which implies a destructive, irreversible operation, but lacks details on permissions required, confirmation steps, error handling, or what happens to dependent data beyond tasks. This is insufficient for a high-risk 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that is front-loaded with the key action and scope. There is no wasted verbiage or redundancy, making it highly efficient and easy to parse for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's high complexity (destructive deletion with cascading effects), lack of annotations, and no output schema, the description is incomplete. It fails to address critical aspects like success/error responses, side effects on related entities, or safety warnings, leaving significant gaps for agent understanding.
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%, with the single parameter 'projectId' documented in the schema. The description does not add any additional meaning or context about the parameter beyond what the schema provides, such as format examples or validation rules, so it meets the baseline for high schema coverage.
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?
The description clearly states the action ('permanently delete') and the resource ('a project and all its tasks'), making the purpose specific and unambiguous. It distinguishes this tool from other deletion tools like delete_label, delete_section, and delete_task by specifying it targets projects and their associated tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives. It does not mention prerequisites (e.g., project must exist), exclusions (e.g., cannot delete if tasks are locked), or suggest alternatives like archiving instead of deletion, leaving the agent with minimal context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 this is a list operation but doesn't describe what 'List all projects' entails—whether it returns a simple array, includes pagination, sorts projects, or shows metadata like project IDs and colors. For a tool with zero annotation coverage, this leaves significant 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It's front-loaded with the core action ('List all projects') and specifies the scope ('in the Todoist account'). Every part of the sentence contributes essential information, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no annotations, no output schema), the description is minimally adequate. It tells the agent what the tool does but lacks details on behavior, output format, or usage context. For a read-only list tool, it meets the bare minimum but doesn't provide enough information for confident use without additional context or trial.
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?
The tool has 0 parameters, and schema description coverage is 100% (though trivial since there are no parameters). The description doesn't need to explain any parameters, which is appropriate. It implies no filtering or options are available, which aligns with the empty input schema. A baseline of 4 is given for zero-parameter tools when the description doesn't mislead about inputs.
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 clearly states the verb ('List') and resource ('all projects in the Todoist account'), making the purpose immediately understandable. It distinguishes this tool from siblings like 'create_project' or 'delete_project' by indicating it's a read operation. However, it doesn't specify whether this includes archived projects or only active ones, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives. It doesn't mention whether this is the primary way to retrieve projects, if there are filtering options elsewhere, or if other tools like 'list_tasks' might be more appropriate for different use cases. The agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 key behavioral traits: the deletion is permanent (irreversible) and tasks are moved to project root (side effect). However, it lacks details on permissions needed, error conditions, or what happens if the section doesn't exist, which are important for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('permanently delete') and includes critical side effect information. Every word earns its place with zero redundancy or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no annotations and no output schema, the description is moderately complete. It covers the permanence and task relocation, but lacks details on permissions, error handling, or response format. Given the complexity of deletion operations, more context would be beneficial for safe agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the single parameter 'sectionId'. The description adds no additional parameter semantics beyond what the schema provides (e.g., format examples, validation rules). The baseline score of 3 reflects adequate but minimal value added.
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 clearly states the action ('permanently delete') and resource ('a section'), making the purpose unambiguous. It distinguishes from sibling tools like 'delete_project' or 'delete_task' by specifying the section resource. However, it doesn't explicitly differentiate from 'move_section' which might also affect sections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternatives. It doesn't mention prerequisites (e.g., needing section ID), when not to use it, or compare with siblings like 'delete_project' or 'move_section'. The agent must infer usage from the name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions filtering but doesn't disclose behavioral traits like pagination (implied by 'limit' parameter), default sorting, authentication needs, rate limits, or what happens with conflicting filters (e.g., 'dueToday' and 'overdue'). This leaves gaps for an AI agent to understand operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('List tasks') and succinctly lists filtering options. Every word earns its place with no redundancy or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is adequate for a read-only list tool but lacks completeness. It covers the what (list tasks with filters) but misses behavioral context (e.g., response format, error handling) and doesn't compensate for the absence of output schema, leaving the agent uncertain about return values.
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%, providing detailed parameter documentation. The description adds minimal value beyond the schema by summarizing filter types ('project, label, priority, due date, or custom filter'), but doesn't explain interactions or constraints (e.g., that 'filter' uses Todoist syntax). Baseline 3 is appropriate as the schema does the heavy lifting.
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 clearly states the verb ('List') and resource ('tasks') with specific filtering capabilities ('by project, label, priority, due date, or custom filter'). It distinguishes from siblings like 'get_task' (singular) and 'quick_add' (creation), but doesn't explicitly contrast with other list tools like 'list_labels' or 'list_projects'.
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 implies usage through the phrase 'optional filtering,' suggesting when to use it (when you need filtered task lists) versus alternatives like 'get_task' (for a single task). However, it doesn't explicitly state when not to use it or name specific alternatives for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 adds valuable context about recurring task behavior that isn't in the schema, but doesn't address important aspects like whether completion is reversible, what permissions are required, or what the response looks like. For a mutation tool with zero annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each earn their place: the first states the core purpose, the second adds crucial behavioral context for recurring tasks. No wasted words, front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with no annotations and no output schema, the description should do more to explain behavioral implications. While it covers the basic action and recurring task nuance, it doesn't address completion permanence, error conditions, or response format. The description is adequate but has clear gaps for a tool that modifies state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the single 'taskId' parameter completely. The description doesn't add any parameter-specific information beyond what's in the schema, but doesn't need to since the schema provides full coverage. Baseline 3 is appropriate when the schema does the heavy lifting.
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?
The description clearly states the verb ('Mark as complete') and resource ('a task'), specifying the action precisely. It distinguishes from sibling 'uncomplete_task' by indicating the opposite operation, and from 'update_task' by focusing specifically on completion status rather than general updates.
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?
The description provides clear context about when to use this tool ('Mark a task as complete') and includes important behavioral guidance for recurring tasks ('completes the current occurrence'). However, it doesn't explicitly state when NOT to use it or mention alternatives like 'update_task' for partial completion scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 explains that Todoist will parse dates, priorities, labels, and projects from the text, which adds useful context about the tool's behavior. However, it lacks details on permissions, error handling, or response format, leaving gaps 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with two sentences that are front-loaded and efficient. Every sentence earns its place by stating the purpose and explaining the parsing behavior without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a mutation tool with no annotations and no output schema), the description is moderately complete. It covers the core functionality and parsing behavior but lacks details on what the tool returns, error conditions, or integration with sibling tools, which could be important for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the 'text' parameter thoroughly. The description adds minimal value by mentioning that the text should be 'natural language' and giving an example, but it does not provide additional syntax or format details beyond what the schema specifies.
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?
The description clearly states the tool's purpose with a specific verb ('add'), resource ('task'), and method ('using natural language'). It distinguishes from sibling tools like 'create_task' by emphasizing the natural language parsing capability, which is a unique feature.
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?
The description provides clear context for when to use this tool ('Quickly add a task using natural language'), but it does not explicitly state when not to use it or name alternatives. The natural language focus implies it's for quick entry versus structured creation, but no explicit exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It effectively communicates the destructive nature ('permanently delete') and clarifies the impact on related data ('tasks will keep their other labels'), which are crucial behavioral traits for a deletion operation. However, it doesn't mention authentication requirements, rate limits, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence) and front-loaded with the core action ('permanently delete a label'), followed by important behavioral context. Every word earns its place, with no redundant information or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no annotations and no output schema, the description does well by emphasizing permanence and clarifying data relationships. However, it could be more complete by mentioning potential error conditions (e.g., what happens if the label doesn't exist) or confirmation requirements, given the high-stakes nature of deletion.
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% (the single parameter 'labelId' is documented in the schema), so the baseline is 3. The description doesn't add any parameter-specific information beyond what's already in the schema, but it does provide important context about what happens when the label is deleted, which relates to the parameter's purpose.
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?
The description clearly states the specific action ('permanently delete') and resource ('a label'), distinguishing it from sibling tools like 'delete_project' or 'delete_task'. It also adds important context about what happens to associated tasks ('tasks will keep their other labels'), which helps differentiate it from tools that might cascade deletions.
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 implies usage context by specifying the permanent nature of deletion and the effect on tasks, but doesn't explicitly state when to use this tool versus alternatives like 'update_label' or 'list_labels'. No explicit guidance on prerequisites, error conditions, or when-not-to-use scenarios is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![todoist-mcp MCP server](https://glama.ai/mcp/servers/rauf543/todoist-mcp/badges/card.svg)](https://glama.ai/mcp/servers/rauf543/todoist-mcp)

Score Badge

Copy to your README.md:

[![todoist-mcp MCP server](https://glama.ai/mcp/servers/rauf543/todoist-mcp/badges/score.svg)](https://glama.ai/mcp/servers/rauf543/todoist-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/rauf543/todoist-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server