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, sections, labels, comments) and actions (create, get, list, update, delete, complete, reopen, move, search). No ambiguity exists—for example, todoist_create_task, todoist_update_task, and todoist_complete_task are well-differentiated, and comment tools are specialized by prefix or general use.
Naming Consistency5/5
All tools follow a consistent snake_case pattern with a 'todoist_' prefix and verb_noun structure (e.g., todoist_create_task, todoist_list_projects). Minor variations like 'todoist_add_context_comment' vs. 'todoist_create_comment' are semantically justified and maintain readability without breaking the pattern.
Tool Count2/5
33 tools is excessive for a Todoist server, making the set feel heavy and potentially overwhelming. While it covers many operations, the count could be streamlined—for instance, batch operations or specialized comment tools might be consolidated without losing functionality, aligning better with typical MCP scopes of 3-15 tools.
Completeness5/5
The tool set provides complete CRUD/lifecycle coverage for all core Todoist entities (tasks, projects, sections, labels, comments), including advanced operations like moving tasks, reopening completed ones, searching, and batch creation. No obvious gaps exist; agents can perform any expected workflow without dead ends.
Average 2.9/5 across 33 of 33 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 3 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
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 but only states 'Create a new project' without disclosing behavioral traits. It doesn't mention authentication requirements, rate limits, whether creation is idempotent, what happens on failure, or the expected response format. 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 extremely concise with just three words, front-loaded with the core action. There's zero wasted text, making it easy to parse quickly while still conveying the basic 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?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after creation, what the tool returns, error conditions, or how it fits within the broader Todoist workflow. The 100% schema coverage helps with parameters but doesn't address broader behavioral 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%, providing good documentation for all 5 parameters. The description adds no parameter information beyond what's in the schema, so it meets the baseline of 3 where the schema does the heavy lifting but doesn't compensate with additional context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new project' clearly states the action (create) and resource (project), but it's vague about scope and doesn't differentiate from sibling tools like todoist_create_task or todoist_create_label. It lacks specificity about what a 'project' entails in Todoist context.
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. There's no mention of prerequisites, when to choose this over todoist_update_project for modifications, or how it relates to sibling creation tools like todoist_create_task or todoist_create_section.
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 only states the action without behavioral details. It doesn't disclose if this is a read-only operation, requires authentication, has rate limits, returns error handling, or what the output includes (e.g., comment content, author, timestamp). This leaves significant gaps for a tool with no 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, front-loaded sentence with zero waste—'Get a comment by ID' is direct and appropriately sized for a simple tool. Every word earns its place, making it highly concise and well-structured.
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, no output schema, and a simple input schema, the description is incomplete. It doesn't explain return values, error cases, or behavioral traits, which are crucial for a get operation. The tool's complexity is low, but the description lacks sufficient context for reliable agent 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 parameter 'comment_id' fully documented in the schema. The description adds no additional meaning beyond the schema, such as format examples or constraints, so it meets the baseline of 3 where the schema does the heavy lifting without compensation needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get a comment by ID' clearly states the action (get) and resource (comment), but it's vague about what 'get' entails—retrieving details, content, or metadata. It distinguishes from siblings like todoist_list_comments (list vs. get by ID) but not from todoist_get_task or todoist_get_project, which share the same 'get by ID' pattern, lacking specificity in verb+resource 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?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a valid comment ID), exclusions, or comparisons to siblings like todoist_list_comments for bulk retrieval or todoist_update_comment for modifications, leaving usage context implied but not explicit.
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 the tool retrieves statistics, implying a read-only operation, but doesn't disclose behavioral traits such as whether it requires authentication, has rate limits, returns aggregated data (e.g., counts, averages), or handles errors. This leaves significant gaps for a tool with no structured safety hints.
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 directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, 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?
Given no annotations and no output schema, the description is incomplete. It doesn't explain what statistics are returned (e.g., counts, time-based metrics), the format of the output, or any limitations. For a tool that likely provides aggregated data, this lack of detail makes it inadequate for effective use by 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%, with the single parameter 'project_id' documented as 'Filter by project ID'. The description doesn't add any meaning beyond this, such as explaining what happens if the parameter is omitted (e.g., returns global statistics) or format examples. With high schema coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get statistics about completed tasks' states a clear verb ('Get') and resource ('statistics about completed tasks'), but it's vague about what specific statistics are returned (e.g., counts, trends, metrics). It doesn't distinguish from sibling tools like 'todoist_list_completed_tasks', which likely lists tasks rather than providing aggregated statistics.
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. For example, it doesn't clarify if this should be used for analytics instead of 'todoist_list_completed_tasks' for detailed task data, or mention any prerequisites like needing completed tasks to exist.
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 'Get a project by ID' but doesn't disclose behavioral traits such as whether this is a read-only operation, what happens if the ID is invalid (e.g., error handling), or any rate limits. The description is minimal and lacks essential context for safe use.
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 four words—and front-loaded with the core action. There's no wasted language, making it easy to parse quickly. It efficiently conveys the basic purpose without unnecessary detail.
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 read operation with one parameter) and lack of annotations and output schema, the description is incomplete. It doesn't explain what is returned (e.g., project details), error conditions, or usage context. For a tool with no structured output information, the description should provide more completeness to guide the agent 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?
Schema description coverage is 100%, with the parameter 'project_id' fully documented in the schema. The description adds no additional meaning beyond what the schema provides, such as format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get a project by ID' clearly states the action (get) and resource (project), but it's vague about what 'get' entails—does it retrieve metadata, full details, or something else? It distinguishes from siblings like 'todoist_list_projects' by specifying retrieval by ID rather than listing all, but lacks specificity about the scope of information returned.
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. For example, it doesn't clarify if this should be used over 'todoist_list_projects' when a specific project ID is known, or mention prerequisites like needing a valid project ID. The context is implied but not explicitly stated.
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 'Get a section by ID' but doesn't disclose behavioral traits such as whether this is a read-only operation, if it requires authentication, what happens on invalid IDs (e.g., errors), or rate limits. This leaves significant gaps in understanding how the tool behaves beyond basic retrieval.
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, front-loaded sentence: 'Get a section by ID'. It's extremely concise with zero wasted words, efficiently conveying the core purpose without unnecessary elaboration.
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, no output schema, and a simple input schema, the description is incomplete. It doesn't explain what 'get' returns (e.g., section details, tasks within), error conditions, or prerequisites, making it inadequate for a tool that might involve data retrieval in a collaborative system like Todoist.
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 parameter 'section_id' fully documented in the schema as 'The section ID'. The description adds no additional meaning beyond this, so it meets the baseline score of 3 for high schema coverage without extra param info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get a section by ID' clearly states the action (get) and resource (section), but it's vague about what 'get' entails—does it retrieve metadata, contents, or something else? It distinguishes from siblings like todoist_list_sections (list vs. get by ID) but lacks specificity about the scope of retrieval.
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. For example, it doesn't clarify if this should be used after todoist_list_sections to fetch details, or if it's for direct access when the ID is known, leaving the agent to 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. 'Update a comment' implies a mutation operation, but it doesn't disclose whether this requires specific permissions, if updates are reversible, what happens to existing comment attributes not mentioned in parameters, or any rate limits/constraints. The description adds minimal behavioral 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 extremely concise with just three words, front-loading the core action ('Update a comment') without any wasted text. Every word earns its place, though this brevity comes at the cost of completeness.
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 (a mutation operation with 3 parameters), lack of annotations, and no output schema, the description is insufficiently complete. It doesn't explain what the tool returns, error conditions, or important behavioral aspects like whether the update is idempotent. For a mutation tool in this context, more detail is needed to be fully actionable.
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 three parameters (comment_id, content, prefix) with their types, descriptions, and enum values. The description doesn't add any meaningful parameter semantics beyond what's in the schema, such as explaining how the prefix interacts with content or providing examples. 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.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update a comment' clearly states the verb ('Update') and resource ('comment'), making the basic purpose understandable. However, it doesn't differentiate this tool from its sibling 'todoist_update_task' or other update tools, nor does it specify what aspects of a comment can be updated beyond what's implied by the parameters.
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 'todoist_create_comment' or 'todoist_delete_comment'. It doesn't mention prerequisites (e.g., needing an existing comment ID) or contextual factors that would influence tool selection.
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. 'Update a label' implies a mutation operation, but it doesn't describe what happens if the update fails, whether changes are reversible, what permissions are required, or what the response looks like. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
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 with just three words ('Update a label'), which is front-loaded and wastes no space. For a tool with a clear name and comprehensive schema, this minimalism is efficient, though it comes at the cost of missing contextual details.
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 a mutation tool with 5 parameters, no annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like error handling, side effects, or return values, leaving significant gaps for the agent to navigate. The schema handles parameters well, but the overall context is insufficient 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 all 5 parameters clearly documented in the schema (e.g., 'label_id', 'name', 'color', 'order', 'is_favorite'). The description adds no additional meaning beyond what the schema provides, such as explaining how 'order' affects sorting or what 'color' values are valid. 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.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update a label' clearly states the verb ('Update') and resource ('label'), making the basic purpose understandable. However, it doesn't specify what aspects of a label can be updated or differentiate this from sibling tools like 'todoist_update_task' or 'todoist_update_project' beyond the resource type. It's adequate but lacks specificity about scope.
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), exclusions, or comparisons to sibling tools like 'todoist_create_label' or 'todoist_delete_label'. Without any usage context, the agent must infer everything from the tool name and schema.
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. 'Update a project' implies a mutation operation but doesn't disclose behavioral traits such as required permissions, whether changes are reversible, rate limits, or what happens to unspecified fields. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
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 appropriately sized and front-loaded, though it could be more informative. Every word earns its place in being direct.
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 5 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain return values, error conditions, or behavioral context. The agent lacks sufficient information to use this tool effectively beyond basic parameter input.
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 with descriptions. The description adds no meaning beyond what the schema provides, such as explaining relationships between parameters or usage examples. 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.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update a project' clearly states the verb (update) and resource (project), but it's vague about what aspects can be updated and doesn't differentiate from sibling tools like todoist_update_task or todoist_update_section. It provides basic purpose but lacks specificity.
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 prerequisites, context, or comparisons with siblings like todoist_create_project or todoist_delete_project. It leaves the agent to 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. 'Update an existing task' implies a mutation operation but doesn't specify what happens (e.g., partial vs. full updates, whether unmentioned fields are preserved, error conditions, or authentication requirements). This is inadequate for a mutation 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 with zero wasted words. It's appropriately front-loaded with the core action, though it lacks detail due to its brevity.
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 'update' entails behaviorally, what the tool returns, or how to handle the many optional parameters. The high parameter count and lack of structured metadata demand more descriptive 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?
The schema description coverage is 100%, with all 12 parameters well-documented in the schema itself. The description adds no parameter-specific information beyond the generic 'update' action, 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.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing task' clearly states the action (update) and resource (task), but it's vague about what can be updated. It doesn't differentiate from sibling tools like todoist_update_comment or todoist_update_project, which follow the same pattern for different resources.
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 task ID), when to use create_task instead, or how it differs from todoist_move_task or todoist_complete_task for task modifications.
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 ('Mark as completed') but doesn't cover critical aspects like whether this is a destructive mutation (likely yes), what permissions are required, how it affects task history, or what happens if the task is already completed. This leaves significant gaps in understanding the tool's 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 extremely concise at just 4 words, with zero wasted language. It's front-loaded with the core action and resource, making it immediately scannable. Every word earns its place by conveying essential information without redundancy.
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 insufficient. It doesn't explain what happens after completion (e.g., task moves to completed list, affects statistics), doesn't mention error conditions (e.g., invalid task_id), and provides no behavioral context beyond the basic action. The agent would need to guess about many aspects of tool behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the single parameter 'task_id' clearly documented. The description adds no additional parameter information beyond what's in the schema. According to scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in the description, which applies here.
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 ('Mark as completed') and the resource ('a task'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'todoist_reopen_task' or 'todoist_update_task' which also modify task status, leaving room for ambiguity in tool selection.
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 and be incomplete), contrast with 'todoist_reopen_task' for undoing completions, or explain when to use this versus 'todoist_update_task' with a status field. This lack of context makes it harder for an agent to choose correctly.
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 tool creates a comment, implying a write operation, but doesn't cover permissions, rate limits, error handling, or what happens on success (e.g., returns a comment ID). This leaves significant gaps for an agent to understand the tool's behavior beyond basic functionality.
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 ('Create a comment on a task or project') and adds a useful detail ('with optional prefix tags'). There is no wasted verbiage, 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?
Given the complexity (5 parameters, nested object, no annotations, no output schema), the description is inadequate. It doesn't explain the attachment parameter's purpose, the mutual exclusivity of task_id and project_id, or what the tool returns. For a creation tool with multiple parameters, more context is needed to ensure proper usage.
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%, so the schema already documents all parameters thoroughly (e.g., content supports markdown, task_id/project_id are mutually exclusive, prefix has enum values). The description adds minimal value by mentioning 'optional prefix tags', which is redundant with the schema. 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 action ('Create a comment') and the target ('on a task or project'), which is specific and distinguishes it from siblings like todoist_delete_comment or todoist_update_comment. However, it doesn't explicitly differentiate from todoist_add_context_comment or todoist_add_research_comment, which might have overlapping purposes, so it's not 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 like todoist_add_context_comment or todoist_add_research_comment, nor does it mention prerequisites (e.g., needing a valid task_id or project_id). It only hints at optional features ('with optional prefix tags'), which is insufficient for clear usage decisions.
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 any behavioral traits such as authentication requirements, rate limits, error handling, or what happens on success (e.g., returns a label ID). For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
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 ('Create a new label') that is front-loaded with the core action. There is no wasted verbiage, repetition, or unnecessary elaboration, making it highly concise and well-structured for quick understanding.
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 a mutation tool (creating a label) with no annotations and no output schema, the description is incomplete. It lacks information on behavioral aspects (e.g., permissions, side effects), usage context, and what the tool returns. While the schema covers parameters well, the overall context for safe and effective use is insufficient, especially compared to siblings that might have more detailed descriptions.
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 input schema has 100% description coverage, with clear documentation for all four parameters (name, color, order, is_favorite). The description adds no parameter semantics beyond what the schema provides, as it doesn't explain the purpose or constraints of the parameters (e.g., color format, order significance). With high schema coverage, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.
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 this tool from siblings like todoist_update_label or todoist_delete_label by specifying it's for creation rather than modification or deletion. However, it doesn't specify what kind of label (e.g., in Todoist's task management system), which keeps it from 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 Todoist account or authentication), compare it to similar tools like todoist_update_label for modifying existing labels, or indicate when not to use it (e.g., for batch operations). This lack of context makes it harder for an AI agent to select the right tool in a workflow.
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 'Create' implies a write operation but doesn't cover permissions, side effects (e.g., impact on existing sections), error handling, or response format. This is a significant gap for a mutation tool without annotation support.
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 no wasted words. It front-loads the core action and resource, making it easy to scan and understand quickly. Every word earns its place, achieving optimal conciseness.
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 lacks details on behavioral traits (e.g., what happens on success/failure), return values, and usage context. For a tool that creates resources, more information is needed to guide 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%, so the schema already documents all parameters (name, project_id, order). The description adds no additional meaning beyond implying a section is created within a project, which is redundant with the schema. Baseline 3 is appropriate as the schema handles parameter documentation adequately.
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 in a project'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'todoist_create_project' or 'todoist_create_task' beyond specifying 'section', which is adequate but not fully distinctive.
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), exclusions, or comparisons to similar tools like 'todoist_update_section' or 'todoist_list_sections', leaving usage context unclear.
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 mentions 'parallel API calls,' hinting at performance or concurrency, but lacks critical details: whether this is a write operation (implied by 'create'), error handling for partial failures, authentication needs, rate limits, or what the response looks like. 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 waste. It's front-loaded with the core action ('create multiple tasks at once') and adds a useful technical note ('uses parallel API calls'), making it appropriately sized and well-structured.
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 details on behavioral traits (e.g., error handling, permissions), usage guidelines compared to siblings, and expected return values. The high schema coverage helps with parameters, but overall context is insufficient 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%, so the schema fully documents the 'tasks' parameter and its nested properties. The description adds no additional parameter semantics beyond what the schema provides, such as explaining batch size limits or interactions between parameters. 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 multiple tasks at once') and resource ('tasks'), making the purpose evident. It distinguishes from the sibling 'todoist_create_task' by specifying batch creation, though it doesn't explicitly mention how it differs in behavior or when to choose one over the other.
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 the sibling 'todoist_create_task' or other alternatives. The description mentions 'parallel API calls' but doesn't explain implications like performance benefits, rate limits, or error handling, leaving the agent without clear 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Delete a comment' which implies a destructive mutation, but doesn't specify whether this requires special permissions, is irreversible, has side effects (e.g., affecting associated tasks), or what happens on success/failure. For a destructive tool with zero annotation coverage, this is a significant gap in transparency.
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 ('Delete a comment') - just three words that directly convey the core action. It's front-loaded with no unnecessary elaboration, making it easy to parse quickly. Every word earns its place by specifying the verb and resource.
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 destructive mutation tool with no annotations and no output schema, the description is incomplete. It doesn't address behavioral aspects like permissions, irreversibility, error conditions, or response format. While concise, it lacks the contextual information needed for safe and effective use, especially given the tool's potentially destructive nature.
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's in the schema. However, schema description coverage is 100% (the comment_id parameter is fully documented in the schema), so the baseline score is 3. The description doesn't compensate but doesn't need to since the schema adequately covers the single parameter.
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 ('Delete') and resource ('a comment'), making the purpose immediately understandable. It distinguishes from siblings like todoist_update_comment or todoist_get_comment by specifying deletion rather than modification or retrieval. However, it doesn't explicitly mention the Todoist context beyond the tool name, which slightly reduces specificity.
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 comment ID), exclusions, or comparisons to siblings like todoist_delete_task or todoist_update_comment. Usage is implied by the name but not explicitly stated in the description text.
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 'Delete' implies a destructive mutation, the description lacks details on permissions required, whether the action is reversible, side effects (e.g., impact on tasks using the label), or error handling. This is a significant gap for a mutation 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 with zero wasted words. It is appropriately sized for a simple deletion tool and front-loads the core action, 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?
Given the tool's complexity as a destructive mutation with no annotations and no output schema, the description is incomplete. It fails to address critical aspects like behavioral traits (e.g., irreversibility, permissions), usage context, or return values, leaving gaps that could hinder an AI agent's ability to invoke 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%, with the parameter 'label_id' fully documented in the schema as 'The label ID to delete'. The description adds no additional meaning beyond this, such as format examples or sourcing instructions. With high schema coverage, the baseline score of 3 is appropriate as the schema handles parameter documentation adequately.
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 ('Delete') and resource ('a label'), providing a specific verb+resource combination. It distinguishes itself from siblings like 'todoist_update_label' by focusing on deletion rather than modification, though it doesn't explicitly differentiate from other delete operations like 'todoist_delete_task' or 'todoist_delete_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 an existing label), exclusions, or comparisons to siblings like 'todoist_update_label' for label modifications or 'todoist_list_labels' for viewing labels before deletion.
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 discloses the destructive nature ('permanently'), which is critical, but lacks other behavioral traits: it doesn't specify permissions required, rate limits, error conditions (e.g., invalid project ID), or what happens to associated tasks/comments. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
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 ('Delete a project permanently'), making it immediately clear. Every word earns its place by emphasizing the irreversible nature.
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 (destructive mutation), lack of annotations, and no output schema, the description is incomplete. It misses critical context: no guidance on prerequisites, error handling, or what to expect after deletion (e.g., success confirmation or side effects). For a permanent deletion tool, this leaves the agent under-informed about risks and outcomes.
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 'project_id' documented in the schema. The description adds no parameter-specific information beyond implying the parameter is needed for deletion. Since schema coverage is high, the baseline is 3, and the description doesn't compensate with additional semantics like format examples or sourcing guidance.
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 ('Delete') and resource ('a project'), specifying it's a permanent deletion. It distinguishes from siblings like 'todoist_update_project' by indicating destruction rather than modification. However, it doesn't explicitly differentiate from other delete operations like 'todoist_delete_task' or 'todoist_delete_section', though the resource name makes this somewhat implicit.
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 project ID from 'todoist_get_project' or 'todoist_list_projects'), warn about irreversible consequences, or suggest alternatives like archiving or updating instead. 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.
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. 'Delete a task permanently' implies a destructive, irreversible mutation, which is useful, but it lacks details on permissions required, error conditions (e.g., invalid task_id), side effects (e.g., associated comments deleted), or confirmation behavior. For a destructive 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 with zero waste. It is appropriately sized for a simple delete operation and front-loads the key action ('Delete a task permanently'). 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 the tool's destructive nature, no annotations, and no output schema, the description is incomplete. It should address critical aspects like irreversibility, permissions, or error handling. The description alone is inadequate for safe and effective use by an AI agent, especially compared to siblings with more complex behaviors.
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 provides. The input schema has 100% description coverage, with task_id documented as 'The task ID to delete'. Since schema coverage is high (>80%), the baseline score is 3, as the description doesn't need to compensate but also adds no extra meaning.
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 'Delete a task permanently' clearly states the verb (delete) and resource (task), and specifies 'permanently' which distinguishes it from siblings like todoist_complete_task or todoist_reopen_task that might archive or hide tasks. However, it doesn't explicitly differentiate from todoist_delete_project or todoist_delete_section which delete different resource types.
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), when not to use it (e.g., if task is completed vs. active), or compare it to siblings like todoist_complete_task for archiving instead of permanent deletion.
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 but only states the basic action without behavioral details. It doesn't disclose whether this is a read-only operation, how results are paginated, what authentication is required, or any rate limits—critical information for a listing tool in an API 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 without any wasted words. It's appropriately sized for a straightforward listing tool, making it easy for an agent 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 tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the return values look like (e.g., comment objects with fields like content, author, timestamp), how to handle multiple comments, or any error conditions. Given the lack of structured data, the description should provide more context for 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%, so the schema already documents both parameters (task_id and project_id) with their descriptions. The description adds no additional parameter semantics beyond implying that comments can be listed for either tasks or projects, which is already clear from 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 ('List') and resource ('comments for a task or project'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'todoist_get_comment' (which likely retrieves a single comment) or 'todoist_create_comment' (which creates rather than lists), missing an opportunity for clearer distinction.
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 sibling tools like 'todoist_get_comment' for retrieving a specific comment or 'todoist_search_tasks' for broader queries, leaving the agent to infer usage context without explicit direction.
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 mentions 'uses Sync API', which hints at the underlying mechanism but doesn't clarify key behaviors like rate limits, authentication requirements, pagination defaults (beyond the schema's 'limit' default), or what the output looks like (no output schema exists). For a read operation with 7 parameters, 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 extremely concise—just one sentence—and front-loaded with the core purpose. Every word earns its place: 'List completed tasks' states the action, '(uses Sync API)' adds implementation context, and 'with optional filters' hints at flexibility. There's no wasted verbiage or redundancy.
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 (7 parameters, no annotations, no output schema), the description is insufficient. It doesn't address behavioral aspects like pagination handling, error conditions, or output format. While the schema covers parameters, the lack of annotations and output schema means the description should compensate more to help the agent use the tool effectively, which it fails to do.
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 7 parameters. The description adds minimal value beyond the schema by mentioning 'optional filters', which is implied by the parameter names. It doesn't provide additional context like filter combinations or precedence rules. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't significantly enhance parameter understanding.
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: 'List completed tasks (uses Sync API) with optional filters'. It specifies the verb ('List'), resource ('completed tasks'), and implementation detail ('uses Sync API'). However, it doesn't explicitly differentiate from sibling tools like 'todoist_list_tasks' or 'todoist_search_tasks', which is why it doesn't achieve 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 minimal guidance: it mentions 'optional filters' but doesn't specify when to use this tool versus alternatives like 'todoist_list_tasks' (for active tasks) or 'todoist_search_tasks' (for broader searches). There's no explicit context about when this tool is preferred or when to avoid it, leaving the agent to 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 'List active tasks', implying a read-only operation, but doesn't clarify if it requires authentication, has rate limits, returns paginated results, or what the output format looks like. This is a significant gap for a tool with no 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 action ('List active tasks') and succinctly mentions optional filters. There's no wasted text, 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 tool's complexity (6 parameters, no annotations, no output schema), the description is insufficient. It lacks details on behavioral traits (e.g., authentication, rate limits), output format, and clear differentiation from sibling tools. For a read operation with multiple filters, more context is needed to guide the agent 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 lists optional filters (project, section, label, or Todoist filter query), which aligns with some parameters in the schema. Since schema description coverage is 100%, the schema already documents all parameters well. The description adds marginal value by grouping filters conceptually but doesn't provide additional syntax or usage details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('active tasks'), making the purpose evident. It specifies 'active tasks' which distinguishes it from sibling tools like 'todoist_list_completed_tasks'. However, it doesn't explicitly differentiate from 'todoist_search_tasks', which might have overlapping functionality, keeping it from 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 mentions 'optional filters' but provides no guidance on when to use this tool versus alternatives like 'todoist_search_tasks' or 'todoist_list_completed_tasks'. There's no mention of prerequisites, exclusions, or specific contexts for usage, leaving the agent with minimal direction.
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 mentions the action 'move' but doesn't specify if this requires special permissions, whether it's reversible, what happens to subtasks, or any rate limits. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding the tool's 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 directly states the tool's purpose with no wasted words. It's front-loaded and appropriately sized for the functionality.
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 insufficient. It doesn't explain what happens when multiple target parameters are provided, what the return value looks like, or any error conditions. Given the complexity of moving tasks in a hierarchy, 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 documents all four parameters thoroughly. The description adds minimal value by implying that project_id, section_id, and parent_id are target destinations, but doesn't provide additional context like format examples or mutual exclusivity rules beyond what the schema states.
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 the resource 'task', specifying the destination options (different project, section, or parent). It distinguishes from siblings like todoist_update_task by focusing specifically on relocation rather than general updates, though it doesn't 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.
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 like todoist_update_task (which might also handle moving), nor any prerequisites or constraints. The description only states what the tool does, not when it's appropriate.
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 ('reopen') but doesn't explain what reopening entails (e.g., does it restore original due dates, move the task back to its original project, require specific permissions, or have side effects like notifications). 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.
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 inadequate. It doesn't cover behavioral aspects like permissions, side effects, or what the tool returns, leaving the agent with insufficient context to use it correctly beyond the basic action.
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 'task_id' clearly documented in the schema. The description adds no additional parameter information beyond implying the task must be completed, which is minimal value. 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 action ('reopen') and the resource ('a completed task'), making the purpose immediately understandable. It distinguishes from siblings like 'todoist_complete_task' by specifying the opposite operation, though it doesn't explicitly contrast with other update or task management tools.
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., the task must be completed), exclusions (e.g., cannot reopen if deleted), or sibling tools like 'todoist_update_task' that might also modify task status.
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 'update' implies a mutation operation, the description doesn't mention permission requirements, whether the change is reversible, what happens to tasks within the section, or what the response looks like. For a mutation tool with zero annotation coverage, this is a significant gap in behavioral 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 extremely concise at just three words - 'Update a section name' - with zero wasted language. It's front-loaded with the core action and resource. Every word earns its place, making this maximally efficient while still communicating the essential 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?
For a mutation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what happens when the update succeeds or fails, what permissions are required, or how this operation relates to other Todoist entities. The description should provide more context about this being a write operation that modifies existing data in the Todoist system.
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 both parameters ('section_id' and 'name') clearly documented in the schema. The description adds no additional parameter information beyond what's already in the structured schema. According to the scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no parameter information in the description.
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 'Update a section name' clearly states the verb ('update') and resource ('section name'), making the purpose immediately understandable. However, it doesn't distinguish this tool from similar sibling tools like 'todoist_update_project' or 'todoist_update_task' - they all update different Todoist entities but follow the same pattern.
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 'todoist_get_section' (for reading) and 'todoist_delete_section' (for removal), there's no indication of when this update operation is appropriate versus creating a new section or using other update tools for different entity types.
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 that context is prefixed with '[Context]', which adds some behavioral detail, but fails to disclose critical traits: whether this is a mutation (likely yes, as it 'Adds'), what permissions are required, if there are rate limits, or what the response looks like. For a tool that modifies data with no 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 action ('Add context information to a task') and includes a key detail ('prefixed with [Context]') without any wasted words. Every part of the sentence earns its place, making it highly concise and well-structured.
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 2 parameters with 100% schema coverage and no output schema, the description is moderately complete. It clarifies the tool's specific purpose but lacks behavioral details (e.g., mutation effects, error handling) and usage guidelines. For a tool that likely modifies data, more context on permissions or side effects would improve completeness, but it's adequate as a minimum viable description.
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 clear descriptions for both parameters ('task_id' and 'context'). The description adds minimal value beyond the schema by implying that 'context' content will be prefixed, but doesn't provide additional syntax or format details. With high schema coverage, the baseline score of 3 is appropriate as the schema does most of 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 verb ('Add') and resource ('context information to a task'), specifying that the context is prefixed with '[Context]'. It distinguishes from generic comment tools like 'todoist_create_comment' by focusing on context-specific formatting. However, it doesn't explicitly differentiate from 'todoist_add_research_comment', which appears to be a similar sibling tool for adding research comments.
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 'todoist_create_comment' or 'todoist_add_research_comment'. It doesn't mention prerequisites, such as needing an existing task, or exclusions, like not using it for general comments. Usage is implied by the name but not explicitly stated.
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 this is an 'Add' operation (implying mutation) but doesn't mention permissions needed, whether the comment is editable/deletable, rate limits, or what happens on success/failure. 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 that communicates the core purpose and key formatting requirement without any wasted words. It's appropriately sized for this tool's complexity and front-loads the essential information.
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 2-parameter mutation tool with no annotations and no output schema, the description is minimally adequate. It explains what the tool does and the formatting requirement, but doesn't address behavioral aspects like permissions, side effects, or error conditions. The schema covers parameters well, but overall context remains incomplete for safe 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?
Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds the formatting constraint 'prefixed with [Research]' for the research content, which provides some additional semantic context beyond the schema's 'Research content (supports markdown)'. This justifies the baseline score of 3 when schema does most of 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 ('Add a research note') and target ('to a task'), with the specific formatting detail 'prefixed with [Research]' that distinguishes it from generic comment tools. However, it doesn't explicitly differentiate from sibling tools like 'todoist_add_context_comment' or 'todoist_create_comment', which likely have different purposes.
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 'todoist_add_context_comment' or 'todoist_create_comment'. There's no mention of prerequisites, appropriate contexts, or exclusion criteria. 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. While 'Create' implies a write operation, the description doesn't mention authentication requirements, rate limits, error conditions, or what happens on success (e.g., returns task ID). It also doesn't clarify if this is an atomic operation or if partial failures are possible with multiple optional fields.
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 ('Create a new task') and mentions key optional features. Every word earns its place with no redundancy or unnecessary elaboration. Perfectly sized for a tool with comprehensive schema documentation.
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 creation tool with 15 parameters, 100% schema coverage, and no output schema, the description is minimally adequate. The schema handles parameter documentation well, but the description lacks behavioral context (no annotations) and doesn't explain return values. It's complete enough for basic understanding but leaves gaps for effective agent usage.
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 15 parameters thoroughly. The description adds minimal value by mentioning 'optional due date, priority, labels, and project/section assignment' - which only covers 5 of the 15 parameters. This meets the baseline of 3 since the schema does the heavy lifting, but doesn't provide additional context beyond what's in 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 verb 'Create' and resource 'new task', specifying it's for task creation. It lists optional fields (due date, priority, labels, project/section assignment) which helps distinguish it from other creation tools like todoist_create_project or todoist_create_label. However, it doesn't explicitly differentiate from todoist_create_tasks_batch (batch creation) or todoist_update_task (updates existing 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 when to choose this over todoist_create_tasks_batch for multiple tasks, or when to use todoist_update_task instead for modifying existing tasks. No prerequisites, constraints, or typical use cases are provided.
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 ('Delete') but doesn't mention critical details like whether this is irreversible, requires specific permissions, or has side effects (e.g., on tasks within the section). This leaves significant gaps 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 extremely concise ('Delete a section'), with no wasted words. It's front-loaded and efficiently conveys the core action, 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?
Given the tool's destructive nature, no annotations, and no output schema, the description is insufficient. It doesn't address behavioral risks, return values, or usage context, leaving the agent with incomplete information for safe and effective invocation.
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 100% description coverage, with 'section_id' clearly documented. The description doesn't add parameter details beyond the schema, but with only one parameter and high schema coverage, a baseline of 3 is appropriate. The description's clarity on the action slightly enhances understanding, warranting a score of 4.
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 ('Delete') and resource ('a section'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'todoist_delete_project' or 'todoist_delete_task' beyond specifying 'section' as the target, which is adequate but not optimal for sibling distinction.
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, such as when to delete a section versus updating it with 'todoist_update_section', or any prerequisites like needing the section ID from 'todoist_list_sections'. It lacks 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 full burden but only states the action without behavioral details. It doesn't disclose if this is a read-only operation, how results are returned (e.g., pagination, format), rate limits, or authentication needs, which are critical for a list 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 ('List all personal labels') that is front-loaded and wastes no words. It directly conveys the core purpose without unnecessary elaboration, making it highly concise and well-structured.
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 a list operation with no annotations and no output schema, the description is incomplete. It lacks details on return values (e.g., format, fields), behavioral traits like pagination or sorting, and doesn't compensate for the missing structured data, making it inadequate for full agent understanding.
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 with 100% schema description coverage, so no parameter documentation is needed. The description doesn't add parameter semantics, but this is acceptable given the lack of parameters, aligning with the baseline for zero parameters.
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 'List all personal labels' clearly states the action (list) and resource (personal labels), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'todoist_list_projects' or 'todoist_list_tasks' beyond the resource type, missing explicit sibling distinction.
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, context for listing labels, or compare to other list tools (e.g., 'todoist_list_projects'), leaving usage unclear beyond the basic purpose.
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. 'List all projects' implies a read operation but doesn't disclose behavioral traits like pagination, rate limits, authentication needs, or whether it returns archived projects. For a tool with zero annotation coverage, this is a significant gap in transparency.
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 ('List all projects') with zero wasted words. It's front-loaded and efficiently communicates the core purpose in three words, making it easy for an AI agent 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?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what 'all projects' includes (e.g., active vs. archived), the return format, or any limitations. For a list operation with no structured context, more detail would be helpful for the agent.
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%, so no parameter documentation is needed. The description doesn't add parameter details beyond the schema, but with no parameters, a baseline of 4 is appropriate as there's nothing to compensate for.
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 'List all projects' clearly states the verb ('List') and resource ('projects'), making the purpose immediately understandable. It distinguishes this tool from siblings like 'todoist_get_project' (singular) and 'todoist_create_project' (creation). However, it doesn't specify scope or filtering details, keeping it at 4 rather than 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 when to prefer 'todoist_list_projects' over 'todoist_get_project' for single projects, or how it relates to other list tools like 'todoist_list_tasks'. No explicit context or exclusions are provided.
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 'search filter' but doesn't disclose behavioral traits such as pagination, rate limits, authentication needs, or what happens with no results. For a search 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 a single, efficient sentence with zero waste. It's appropriately sized and front-loaded, clearly stating the tool's purpose without 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 4 parameters with full schema coverage but no annotations or output schema, the description is minimally adequate. It covers the basic purpose but lacks details on behavior, usage context, and output, leaving room for improvement in a search tool 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 4 parameters. The description adds minimal value by implying the query is for content-based filtering, but doesn't provide additional syntax, format details, or examples beyond what the schema states. 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 verb ('search') and resource ('tasks'), specifying the search is 'by content using Todoist search filter'. It distinguishes from siblings like todoist_list_tasks by indicating filtering capability, though it doesn't explicitly contrast with other search-related tools (none exist in siblings).
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 todoist_list_tasks or other filtering methods is provided. The description implies usage for content-based searches but lacks explicit context, prerequisites, or exclusions.
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 'Get a single task by ID,' which implies a read-only operation but doesn't disclose behavioral traits such as authentication requirements, rate limits, error handling (e.g., what happens if the task ID is invalid), or the format of returned data. This leaves significant gaps for a tool with no 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 ('Get a single task by ID') that is front-loaded with the core purpose. There is no wasted verbiage, 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 simplicity (1 parameter, 100% schema coverage) but lack of annotations and output schema, the description is incomplete. It doesn't address behavioral aspects like authentication, errors, or return values, which are crucial for a read operation. This is inadequate for a tool with no structured output documentation.
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 input schema has 1 parameter with 100% description coverage ('The task ID'), so the schema fully documents the parameter. The description adds no additional meaning beyond what the schema provides, such as format examples or constraints. Baseline is 3 when schema coverage is high (>80%).
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 'Get a single task by ID' clearly states the verb ('Get') and resource ('task'), specifying it's for a single task identified by ID. It distinguishes from siblings like 'todoist_list_tasks' (which retrieves multiple tasks) and 'todoist_search_tasks' (which uses search criteria). However, it doesn't explicitly mention what 'Get' entails (e.g., retrieving task details), making it slightly less specific than 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific task ID, as opposed to listing or searching tasks. It doesn't provide explicit when-not-to-use guidance or name alternatives like 'todoist_list_tasks' for multiple tasks, but the context is clear from the tool name and description. No misleading information is present.
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 it's a list operation but doesn't disclose behavioral traits like pagination, rate limits, authentication needs, or what happens when no project_id is provided. The description is minimal and misses key operational details for a tool with no 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 with zero waste. It's front-loaded with the core action and includes the optional parameter note, making it appropriately sized for its 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 no annotations, no output schema, and a simple parameter, the description is incomplete. It doesn't explain return values, error conditions, or behavioral aspects like whether it's a read-only operation. For a list tool with minimal structured data, more context 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 already documents the single parameter 'project_id' with its description. The description adds marginal value by mentioning 'optionally filtered by project', but doesn't provide additional context like format examples or filtering logic beyond what the schema states.
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'), making the purpose immediately understandable. It distinguishes from siblings like 'todoist_get_section' (singular retrieval) and 'todoist_list_projects' (different resource). However, it doesn't specify scope beyond optional filtering, leaving some ambiguity about whether it lists all sections globally or within a context.
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 'optionally filtered by project', suggesting when to use the parameter. However, it lacks explicit guidance on when to use this tool versus alternatives like 'todoist_list_projects' or 'todoist_get_section', and doesn't mention prerequisites or exclusions.
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/DevonGroff/todoist-mcp/badges/card.svg)](https://glama.ai/mcp/servers/DevonGroff/todoist-mcp)

Score Badge

Copy to your README.md:

[![todoist-mcp MCP server](https://glama.ai/mcp/servers/DevonGroff/todoist-mcp/badges/score.svg)](https://glama.ai/mcp/servers/DevonGroff/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/DevonGroff/todoist-mcp'

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