Todoist AI MCP Server

Official

by Doist

Overview Schema Related Servers Score Discussions

TypeScript

Remote

Server Quality Checklist

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

Latest release: v13.1.3
Disambiguation2/5
Several tools appear to overlap: 'fetch' and 'fetch-object' both retrieve objects by ID, 'search' overlaps with 'find-tasks' and 'find-projects', and multiple analytics tools like 'get-overview', 'get-project-health', and 'get-project-activity-stats' serve similar purposes. While some descriptions distinguish them, an agent could easily select the wrong tool.
Naming Consistency2/5
Naming is inconsistent: most tools use verb-noun (add-tasks, find-sections), but some use object-verb (project-move) or noun-based (project-management). Additionally, retrieval verbs are mixed across 'find' (find-tasks), 'get' (get-project-health), 'fetch' (fetch-object), and 'search' (search), creating confusion.
Tool Count2/5
At 47 tools, this server is extremely large for an MCP surface. Even accounting for the breadth of Todoist's API, the tool count exceeds the range where agents can easily navigate and select appropriate tools.
Completeness4/5
The tool set covers most major Todoist entities (tasks, projects, sections, comments, reminders, labels, filters) and includes advanced features like analytics, templates, and workspaces. However, some operations like moving tasks between sections/projects or assigning labels to tasks are not explicitly exposed, relying on update-tasks to handle them implicitly.
Average 4.1/5 across 47 of 47 tools scored. Lowest: 3.2/5.
See the Tool Scores section below for per-tool breakdowns.
- 32 of 33 community issues answered or closed in the last 6 months
- 107 commits in the last 12 weeks
- Last stable release on September 2, 2026
- 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?
The description adds no behavioral information beyond what annotations already declare (destructiveHint=true, readOnlyHint=false). It does not disclose partial update semantics, error handling, or what happens if a filter id does not exist. The sole phrase 'with new values' implies overwriting but gives no specifics. Since annotations carry the destructive/read-only hints, the description offers minimal additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no fluff or redundancy. It front-loads the core action ('Update') and the target ('personal filters'). While it could be slightly expanded, it is appropriately concise for a tool whose parameters are fully described in the schema.
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 (array parameter with nested objects, multiple optional fields) and the presence of an output schema, the description is quite thin. It does not explain partial update behavior (whether omitted fields are left untouched), prerequisite for existing filters, or potential side effects beyond the general destructive hint. The schema covers parameter definitions, but the description leaves out essential usage context for an update 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 baseline is 3. The description adds no parameter-specific meaning beyond the schema. It does not clarify that only the provided fields are updated, nor does it explain the editing behavior for optional fields. The schema itself already documents each parameter and the required id/color pair.
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 states a clear purpose: updating existing personal filters with new values. It identifies the resource (filters) and the action (update). It does not explicitly list which fields can be updated (name, color, query, favorite), but the schema provides that detail, and the description distinguishes from creation ('existing').
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 gives no guidance on when to use this tool versus alternatives like add-filters or find-filters. It does not mention that this is for modifying already-created filters, nor does it point to any sibling tool for other operations. The user must infer usage solely from the verb 'update' and the 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?
Annotations indicate it's a mutating, non-idempotent operation, but the description adds no further behavioral context (e.g., return values, potential side effects, whether duplicates are allowed). Since annotations don't provide rich details, the description's minimalism leaves the agent uninformed.
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, straightforward sentence with zero waste. It is front-loaded and immediately clear, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema covers all parameters thoroughly, and an output schema exists, so return values are presumably documented elsewhere. However, the description lacks context about batch behavior, workspace handling, or ordering. For a simple creation tool, this is adequate but not complete; the agent would need to rely on schema examples or terse 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 detailed parameter descriptions (e.g., color enum with defaults, workspace resolution, parentId for sub-projects). The tool description adds nothing beyond the schema, but the schema itself is sufficient, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Add') and resource ('projects'), making the action unambiguous. It clearly distinguishes from sibling tools like add-tasks or add-sections, which operate on 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 (e.g., update-projects for modifications, find-projects to query). It doesn't mention prerequisites, scoping, or exclusions. Usage is only implied by the tool's existence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is transparent that this creates new non-read-only sections, and annotations already flag readOnlyHint=false, destructiveHint=false, and idempotentHint=false. However, it adds little beyond that, omitting potential duplicate handling, batch behavior, or failure semantics.
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 no filler. Every word contributes to stating the operation and target resource.
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 simple create tool with full schema coverage and an output schema, the description is minimally viable. It lacks usage alternatives and behavioral nuance, but the schema covers the single parameter adequately.
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 parameter meaning is fully handled by the input schema. The description adds no extra semantic detail beyond the schema, which is acceptable but not value-adding.
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 states a specific action ('Add') and resource ('new sections to projects'), making the tool's purpose clear. It implicitly differentiates from update-sections by using 'new sections', but does not explicitly name any alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to prefer this tool over alternatives like find-sections or update-sections, nor does it mention prerequisites or exclusions. Usage is only implied by the verb 'Add'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds contextual scope ('personal', 'new') beyond the annotations, which only indicate readOnlyHint=false. It implies a write operation but does not disclose expected outcomes, error conditions, or permission requirements. With annotations present, this meets the baseline but adds limited value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff, delivering the core purpose efficiently. It is adequately concise, though it could benefit from a brief note on usage or outcomes without becoming verbose.
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?
The tool is simple (one array parameter) with a rich schema and output schema available. The description covers the essential purpose but omits any mention of behavior on duplicate names or whether labels are applied to a specific workspace. It is sufficient for a straightforward creation tool but lacks additional context that might be helpful, yielding a moderate score.
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 struct definition fully documents each parameter (name, color, order, isFavorite). The description adds no parameter-specific information, consistent with the baseline of 3 when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add one or more new personal labels' clearly identifies the verb (add), resource (labels), and scope (new, personal). It distinguishes from sibling 'update-labels' by specifying 'new' and 'personal', making the purpose unambiguous.
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 usage guidance is provided beyond the basic statement. It does not explain when to use this tool versus alternatives like 'update-labels' or 'find-labels', nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the at-least-one-filter constraint but does not disclose behavior such as whether completed tasks are included or excluded, which is relevant given the sibling find-completed-tasks tool. It adds some but not rich 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense, front-loaded sentence with no filler or repetition. It introduces the main verb and resource first, then efficiently lists the supported filter dimensions and the mandatory-filter requirement. It is appropriately sized, though slightly long as one sentence.
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 tool with 12 parameters, full schema coverage, rich annotations, and an output schema, the description is mostly adequate and correctly emphasizes the required-filter constraint. However, it omits how this tool relates to sibling search tools, especially whether it includes or excludes completed tasks, which is a material semantic gap.
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 baseline of 3 applies. The description summarizes filter categories and specifically mentions filterIdOrName, but it does not add new information about parameter syntax, defaults, or relationships beyond what the schema already provides.
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 finds tasks and enumerates specific search dimensions: text, project/section/parent container, responsible user, labels, raw Todoist filter, and saved filter. It does not explicitly differentiate this from sibling tools like find-tasks-by-date or find-completed-tasks, so it loses the top score.
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 provides a clear precondition: 'At least one filter must be provided,' and the enumerated filter modes imply when the tool is appropriate. However, it gives no explicit guidance on when to choose this tool over the sibling find-tasks-by-date or find-completed-tasks, leaving some selection ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a read-only, idempotent, non-destructive operation. The description adds behavioral context by naming the returned status values and optional contextual detail, but it does not disclose potential performance implications, rate limits, or other operational caveats beyond what the schema already notes about large output.
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 two sentences, front-loaded with the primary action and output, and the second sentence gives useful parameter guidance without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich annotations, 100% parameter coverage, and presence of an output schema, the description is mostly complete. It lacks alt-tool guidance for 'analyze-project-health', but that is primarily covered by the usage guidelines dimension; otherwise the description adequately supports correct 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 parameters are already well documented. The description adds minimal parameter-related value beyond what the schema provides; 'includeContext=true for full detail' is essentially restated 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 tool performs a health assessment for a project and lists key outputs: completion progress and health status values. However, it does not explicitly differentiate itself from the sibling tool 'analyze-project-health', which may serve a similar purpose.
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 only usage guidance is the parameter-level instruction 'Use includeContext=true for that full detail.' The description does not state when to choose this tool over alternatives like 'analyze-project-health', 'get-project-activity-stats', or 'get-productivity-stats'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, which informs the agent of the operation's safety profile. The description adds the explicit archive/unarchive semantics but does not explain side effects like whether the project is hidden or if collaborators are notified. This is adequate given the annotations cover the core behavioral aspects.
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 that immediately conveys the action and target. It wastes no words and includes no filler, earning a top score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a low-complexity tool and an output schema present, the description need not explain return values. The archive/unarchive toggle is simple, and the description plus annotations sufficiently cover the operation's context. Minor gaps like error handling or invalid IDs are not expected to be in a description at this level.
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 already documents both parameters ('action' and 'projectId') with 100% coverage, so the description rests at baseline 3. The description's phrase 'by its ID' mirrors the schema's projectId description and the enum options, adding no new meaning. No additional parameter details are needed.
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 function: 'Archive or unarchive a project by its ID,' using a specific verb and resource. It distinguishes this tool from siblings like add/update/find projects through the unique action words, though it does not explicitly contrast with any sibling, such as 'project-move'.
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 instead of alternatives, nor does it discuss prerequisites or context. There is no mention of when archiving is appropriate or when to use a different project-management sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about the breadth of data returned (e.g., current local time, plan) but doesn't disclose any additional behavioral traits like authentication requirements or data freshness. This meets the baseline given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a clear main clause and a list of attributes. It is efficient and front-loaded with the purpose. Each listed item adds value, and there is no padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema is present, the description focuses on the scope of the data. It lists the key fields, which is sufficient for a simple read-only tool with no parameters. Minor gaps like any special handling for timezones are not critical for this level of complexity.
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 zero parameters, so the baseline is 4. The description compensates by detailing what information is returned, which clarifies the output without needing parameter explanations.
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 fetches comprehensive user information and lists specific fields (ID, name, email, timezone, etc.). It distinguishes from siblings like get-productivity-stats by focusing on core user profile data, though it doesn't explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention scenarios, prerequisites, or exclusions. This is a gap for a tool that could overlap with others like get-overview or get-productivity-stats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already indicates destructiveHint: true, and the description's word 'update' implies modification without adding further detail. No contradiction exists, but the description does not elaborate on side effects (e.g., whether missing fields are reset, auth requirements, or irreversible effects). Since annotations provide the core safety info, this is adequate but not enhanced.
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, concise sentence with no fluff. It communicates the core function efficiently without redundant 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?
While the schema provides detailed field descriptions, the tool description lacks context on return values (though an output schema exists) and does not explain partial update semantics or any side effects. It is minimal but functional, leaving some ambiguity about the exact behavior of the update operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all parameters with descriptions (100% coverage), so the description adds no extra meaning. The baseline is 3 because the schema already provides adequate parameter documentation. The description does not clarify edge cases like the necessity of 'color' or behavior of omitted optional fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Update multiple existing projects with new values.' It specifies the resource (projects) and that it's a batch update (multiple). While it doesn't explicitly differentiate from other update tools, the resource type is unambiguous, making the purpose clear.
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 usage is implied: if you need to update existing projects, this tool is appropriate, as opposed to add-projects or update-sections. However, there is no explicit guidance on when to choose this over alternatives, and no mention of prerequisites or constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag this as destructive, so the description does not need to repeat that. It adds the batching and scope idea ('multiple existing sections'), but it does not disclose what happens for nonexistent IDs, partial failures, or whether omitted optional fields are preserved or cleared.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. The phrase 'new values' is slightly generic, but overall the description is appropriately concise for the tool's simple parameter shape.
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 batch mutation tool, this is only minimally complete: the schema covers the inputs and the annotation covers destructiveness, but the description does not clarify what happens if one of the section ids is invalid or whether omitted fields are left unchanged. This is important context for a destructive batch 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%, and the input schema already explains the sections array, id, name, and description clearing semantics. The description adds little param-level value beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Update') and a specific resource ('existing sections'), and it conveys the batch nature ('multiple'). This clearly differentiates it from sibling tools such as add-sections and find-sections.
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?
It implies the tool should be used to modify existing sections, but it does not explicitly state when not to use it or mention alternatives like add-sections for creation or find-sections for discovery. The usage guidance is therefore only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare non-read-only, non-destructive, and idempotent. The description adds the context transition (personal vs workspace) but no further behavioral details such as permission requirements, visibility implications, or side effects on collaboration. It does not contradict annotations.
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?
A single, front-loaded sentence conveys the core purpose with no redundancy. Every word earns its place.
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 5-parameter tool with conditional requirements (workspaceId needed for move-to-workspace), the description is minimal. It does not explain the move's impact or preconditions, though the schema covers parameter semantics. With an output schema present, return values aren't needed, but the behavioral implications of moving remain under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all parameters. The description itself adds no parameter-specific meaning beyond the schema, thus meeting the baseline but not exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Move') and resource ('project') and clearly scopes the operation to between personal and workspace contexts. This distinguishes it from sibling tools like add-projects, update-projects, or find-projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case (relocating a project between contexts) but does not explicitly state when to use this tool versus alternatives like update-projects or project-management. No exclusions or alternative references are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already communicate that this is not read-only and not destructive. The description adds context about reminder types and the taskId requirement, but it does not disclose additional behavioral details such as duplicate behavior, notification delivery defaults, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. The core action is in the first sentence, followed by a concise list of reminder types and the key taskId constraint, with no redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the schema with multiple reminder variants, the description gives enough orientation to understand the domain and the three supported modes. The schema covers structural details like maxItems and per-field descriptions, and an output schema exists, so the absence of return-value details is acceptable.
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 provides very high description coverage (100%), so the description does not need to compensate heavily. It does summarize the three reminder categories and the taskId requirement, but it adds little beyond what the input schema already describes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Add reminders to tasks.' It also distinguishes this from sibling tools like update-reminders and find-reminders by specifying creation as the operation and enumerating the three reminder types.
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 usage is implied well: when you want to add reminders to tasks, use this tool. However, there is no explicit when-not-to-use guidance or mention of alternatives, such as using update-reminders to modify existing reminders.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnly=false, and idempotent=false, so the safety profile is covered. The description itself adds no additional behavioral context such as irreversibility, side effects, or relationship to other states, but it does not contradict the annotations.
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 one sentence, front-loaded, and contains no filler or redundant wording. Every part earns its place: the action, the resource, and the input basis.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter batch mutation tool backed by rich annotations and an output schema, the description provides enough to understand the core operation. It could mention the relationship to uncomplete-tasks or emphasize the destructive nature, but the annotations already supply the essential safety signal.
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 fully describes the only parameter, 'ids', including that it is an array of strings with minItems 1. The description repeats the concept of task IDs without adding extra meaning, constraints, or input-format details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description is specific: 'Complete one or more tasks by their IDs' clearly states the verb, resource, and required input. It also distinguishes the tool from sibling tools like uncomplete-tasks and update-tasks by naming the exact task-completion action.
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 intended usage is implicitly clear: provide task IDs and mark those tasks as completed. However, there is no explicit guidance about when not to use it, how it differs from update-tasks, or that tasks could later be reversed via uncomplete-tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, so the safety profile is covered. The description adds that the full contents are returned. With annotations present, the bar is lower, and the description adds a small amount of context but doesn't disclose any potential pitfalls or specific behaviors beyond the ID format.
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 two sentences, extremely concise, and free of fluff. Every word contributes to clarity. It front-loads the action and then specifies the ID format requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only fetch by ID, the description is sufficient. Output schema exists, so return details are not needed. It covers the essential ID format and clarifies the scope (task or project). Rich annotations fill the remaining 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% for the single id parameter, including the required format. The description repeats that format, adding minimal extra meaning. Baseline 3 is appropriate since the schema already fully describes the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches full task or project contents by ID. It uses a specific verb (Fetch) and resource type (task/project), and the ID format is explicitly specified, distinguishing it from generic tools like fetch-object.
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 for tasks and projects, but does not explicitly contrast with alternatives like fetch-object or provide guidance on when to use this tool over others. It lacks explicit exclusions or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds useful context by scoping the search to tasks and projects and specifying the result fields, going slightly beyond the structured annotations.
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?
Two tight sentences, front-loaded with the action and scope, followed by a relevant output summary. Every sentence contributes meaning and there is no filler or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low parameter count, read-only annotations, and presence of an output schema, the description is largely sufficient. It clearly defines scope and result contents, though it does not mention result limits, ordering, or any search syntax nuances, but these are not critical for this simple search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single query parameter has 100% schema description coverage and a clear explanation ('The search query string to find tasks and projects'). The tool description adds no additional semantic detail beyond the schema, so 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') and clearly identifies the target resources ('tasks and projects in Todoist') plus the return shape ('IDs, titles, and URLs'). It distinguishes itself from more specialized find-* siblings by indicating a broad cross-resource search.
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 gives no explicit guidance on when to use this tool instead of the many sibling find-tasks, find-projects, or find-completed-tasks tools. Whether this should be preferred over those alternatives for unstructured queries is left completely implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the description doesn't need to state destructiveness. It adds valuable context about atomic rollback on failures, which is a behavioral trait not captured in annotations. It is consistent with annotations, and the mention of operation types (assign, unassign, reassign) reinforces the mutating nature.
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 two sentences, front-loaded with the core purpose, and contains no filler. Every sentence adds value: the first states the scope and operations, the second adds the atomic rollback detail. This is 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?
While the description mentions atomic rollback and the operation types, it omits specifics like the conditional requirement of responsibleUser for assign/reassign or the availability of dryRun. However, the schema covers these details, and an output schema exists, so the description does not need to explain return values. For a tool with moderate complexity and full schema coverage, this is adequate but not exhaustive.
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 all parameters are fully described in the schema. The description does not add extra meaning beyond what the schema provides; it only gives a high-level overview. The description mentions 'atomic rollback' but that's not parameter-specific. Baseline 3 is appropriate given the complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Bulk assignment operations for multiple tasks' and enumerates the specific operations (assign, unassign, reassign). It distinguishes from siblings by focusing on assignment operations and bulk scope, effectively covering verb+resource+scope.
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 for bulk assignment tasks but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or when-not-to-use guidance. The term 'bulk' suggests multiple tasks, but no direct comparison to individual assignment tools is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey the mutation safety profile (readOnlyHint=false, destructiveHint=false), and the description adds the semantic effect of reopening completed tasks. It does not disclose edge cases like behavior for already-uncompleted tasks or side effects, but it does not contradict the annotations.
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 where every word adds value: 'Uncomplete (reopen)' clarifies terminology, 'one or more' maps to the array type, 'completed tasks' defines the target set, and 'by their IDs' specifies the input. There is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one required parameter, no nested objects), full schema coverage, and presence of an output schema, the description is sufficient. It clearly communicates the action, target, and input, and nothing important is missing for an agent to select and invoke this tool 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 coverage for the single required parameter is 100% with a clear description for 'ids'. The tool description only reiterates 'by their IDs' and adds no new format, type, or behavior details beyond what the schema already provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Uncomplete (reopen)' and clearly identifies the resource ('completed tasks') and the input mechanism ('by their IDs'). This distinguishes it from sibling tools like complete-tasks and update-tasks by specifying both the action and the target state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives implied usage context: it is for completed tasks that need to be reopened, and IDs are required. However, it does not explicitly state when not to use it or mention alternatives, such as using complete-tasks for the inverse operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare `readOnlyHint: true` and `idempotentHint: true`, so safety is established. The description adds value by listing the returned fields (ID, name, plan type, role, etc.) but doesn't add behavioral nuances like rate limits, auth scope, or pagination, which would be a bonus.
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 two sentences long, leads with the action and scope, and efficiently enumerates the returned data fields. Every word earns its place with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with zero parameters, read-only annotations, and a provided output schema, the description is complete enough. It could mention pagination or absence of filtering, but the phrase 'all workspaces' handles it adequately for most agents.
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?
There are zero parameters, and the schema coverage is 100% (vacuously). The baseline is 4 for no params; the description doesn't need to explain parameters, but it also doesn't add any extra clarity about optional query capabilities (none exist).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('all workspaces') and explicitly scopes to 'the authenticated user'. It distinguishes itself from the many 'find-*' sibling tools by indicating a full, unfiltered listing.
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 usage is implied—it's the obvious list operation for workspaces—but there is no explicit guidance on when to use this versus the `find-*` alternatives or any exclusions. It doesn't say 'use this instead of X' or mention context like pagination.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are present (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds useful context that filters are 'saved custom views' and 'personal,' but it does not disclose potential side effects, duplicate handling, or other behavioral details. This adds some value beyond annotations but not rich 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 two sentences, front-loaded with the core action and a brief definition of the domain object. Every word earns its place; no redundant or vague filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with full schema coverage and an output schema, the description is sufficiently complete. It tells the agent what the tool does, the domain concept, and the personal scope, which is enough for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with detailed per-field descriptions for name, color, query, and isFavorite. The tool description itself adds no parameter-specific meaning, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add one or more new personal filters') and defines the domain concept ('Filters are saved custom views using query syntax to organize tasks'). The verb+resource combination distinguishes it from siblings like update-filters and find-filters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool — creating new personal filters. It does not explicitly mention when not to use it or call out alternatives like update-filters, but the add/update distinction is strongly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds context about granularity and time window but does not disclose additional behavioral aspects like handling of missing data or aggregation details. This is adequate given the 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 two sentences, directly states the function, and includes a usage note. No filler or redundancy, earning a perfect score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only statistics tool with an output schema, the description covers the essential purpose, scope, and use case. It does not need to explain return format since the output schema exists, and annotations cover safety. It is complete for the tool's complexity.
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 coverage is 100%, so all parameters are documented in the schema. The description adds contextual meaning (e.g., 'daily' and 'weekly' align with weeks and includeWeeklyCounts) but does not deeply explain parameter semantics beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'project activity stats' (task completion counts), with scoping details (daily, optional weekly, time window). It distinguishes from siblings like get-productivity-stats and find-activity by focusing on project-specific completion trends.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case ('identifying completion trends and patterns'), which implies when to use it. However, it does not explicitly mention alternatives or when not to use it, so it lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds context by noting the output is 'aggregated' and scoped 'across all projects', which goes beyond the schema and helps the agent understand the tool's behavior. No contradiction with annotations.
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 two sentences, front-loaded with the primary action and scope, then provides input details and a use case. Every sentence adds value and there is no wasteful repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with a rich output schema, high schema parameter coverage, and strong annotations, the description fully covers purpose, input semantics, and usage context. No additional behavioral or output details are necessary, and the agent has enough information to select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description only restates what the schema already says ('Accepts workspace name or ID, with optional project ID filtering') without adding additional format, defaults, or edge-case semantics, so it earns the baseline score.
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 a specific verb ('Get') and resource ('aggregated health and progress insights across all projects in a workspace'), which makes the core purpose unambiguous. It differentiates from project-specific tools by the 'across all projects' scope, though it does not explicitly name sibling alternatives or contrast with tools like get-productivity-stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Useful for a cross-project health overview' provides a clear context for when to use this tool. However, it does not mention when not to use it or explicitly point to alternative sibling tools, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations confirm non-read-only, non-idempotent, non-destructive behavior, and the description adds context by noting collaborator assignment and the ability to add to multiple locations. This complements the structured fields meaningfully.
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?
Two concise, front-loaded sentences with no redundancy. Every word adds value, specifying both action and key capability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with a rich schema and existing output schema, the description covers the essential use case without over-explaining. It could mention batch limits (already in schema) but overall is sufficiently complete for an add-operation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with comprehensive per-field descriptions. The tool description offers minimal additional semantic value beyond the schema, only hinting at project/section/parent through the description, which is already encoded in the schema properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb+resource combination: 'Add one or more tasks to a project, section, or parent.' It clearly defines the action and scope, and mentions a distinguishing capability ('Supports assignment to project collaborators').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (adding tasks) and references destinations (project, section, parent) that suggest scope, but it does not explicitly mention alternatives or when not to use it. Clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It adds nuance beyond the annotations (destructiveHint, idempotentHint) by specifying that workspace projects must be archived before deletion, while personal projects can be deleted regardless. It also implies that deletion of projects is permanent and that archived projects are found via find-projects. It is consistent with the annotations and provides additional operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded: it lists the entity types in the first clause, then gives a focused note about project deletion and the archived subset. No unnecessary words, no fluff. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the range of deletable types and the nuance about project deletion, the description is quite complete. It covers the full scope, warns about the workspace archive rule, and references find-projects for archived ones. It omits explicit description of return behavior, but the presence of an output schema and the destructiveHint annotation make that acceptable. Overall, it provides sufficient operational context for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters (id, type) are fully described in the schema (100% coverage), including enum values for type. The description re-lists the allowed types and mentions the usage of ID, which adds little beyond what the schema already provides. The baseline of 3 is appropriate because the description does not deepen the meaning of the parameters beyond what is given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that it deletes a project, section, task, comment, label, filter, reminder, or location_reminder by ID. It explicitly lists all supported types and uses a specific verb ('Delete') with the resource, distinguishing it as the deletion tool among sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear conditional guidance for project deletion: archived vs. active, workspace (must be archived first) vs. personal (no prior requirement). It also directs to find archived projects via find-projects if needed, offering a context for use. No explicit 'when-not-to-use' is given because no other delete tool exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations (readOnlyHint, idempotentHint, destructiveHint) already convey the non-mutating nature. The description adds no extra side-effect information, but it does not contradict the annotations either. Given the annotations cover the key behavioral aspects, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that conveys all essential information without unnecessary elaboration. It is well-structured and easily parsed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the input requirements and the purpose. While it does not specify the return format, for a straightforward find operation this is not critical. The absence of output schema is not a major gap given the simplicity of the tool.
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 description adds the mutual exclusivity rule that is not evident from the schema alone, which is vital for correct usage. However, it does not elaborate beyond that; the schema descriptions for individual parameters are minimal, but the description compensates with the exclusivity constraint.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds comments by task, project, or ID, and the verb 'find' specifies a read-only search operation. It distinguishes itself from sibling tools like find-tasks or find-projects by focusing specifically on comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states that exactly one of taskId, projectId, or commentId must be provided, which is a crucial usage constraint. While it does not explicitly contrast with alternatives, the tool's purpose is unambiguous for comment lookup scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's read-only nature is consistent. The description adds value by explaining the distinction between time-based (reminderId) and location reminders (locationReminderId), which is behavioral context not present in the annotations alone.
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 concise, two sentences that front-load the primary use case (find by task ID) and then clarify the ID types. No unnecessary words or repetition, 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple finder with three optional parameters and an output schema, the description is mostly sufficient. It covers all parameter use cases and the read-only nature. A minor gap is that it doesn't explicitly state that only one of the three parameters should be provided at a time, but this is implied and unlikely to cause major issues.
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 baseline is 3. The description slightly reinforces the parameter semantics by restating the reminderId/locationReminderId distinction, but it adds little beyond the existing schema descriptions. The schema already provides clear meaning for each parameter, so the description offers marginal extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Find') and resource ('reminders'), and differentiates between finding by task ID (returns all reminder types) and by specific reminder ID. This effectively distinguishes it from sibling tools like add-reminders and update-reminders, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: use taskId to retrieve all reminders for a task, or use reminderId/locationReminderId for specific reminder types. While it doesn't explicitly mention alternatives or exclusions, the parameter-specific guidance gives the agent a clear idea of when to use each input, which is adequate for a simple finder tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive traits. The description adds valuable non-obvious behavior: startDate='today' includes overdue items, and the default responsibleUserFiltering='unassignedOrMe' excludes tasks assigned to others. This gives an agent meaningful insight beyond the schema and annotations.
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?
Two sentences with no filler. The core action is front-loaded, followed only by the two non-obvious defaults that an agent would most likely misjudge. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema, output schema, and safety annotations, the description is largely sufficient. It highlights the most important defaults and the date-range scope. It could slightly improve by mentioning when to use this instead of sibling find tools, but the schema covers the remaining parameter semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds interpretive value by calling out that 'today' includes overdue items and that the default responsible filtering excludes other people's tasks, which helps an agent understand real-world consequences of the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get tasks by date range.' This clearly distinguishes it from sibling tools like find-tasks or find-completed-tasks because the date-range scope is explicit. It also communicates two important default behaviors that refine the tool's purpose.
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 the tool is for date-based task retrieval by saying 'Get tasks by date range,' but it does not explicitly state when to prefer this tool over find-tasks or find-completed-tasks. It provides useful behavioral context about defaults but no explicit exclusions or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint: true, readOnlyHint: false, and idempotentHint: false. The description simply says 'update' and does not add context such as irreversibility, permission requirements, or that content will be overwritten. Since annotations cover the core behavioral traits, the description adds minimal extra transparency, warranting a score of 3.
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, concise sentence that conveys all necessary information without superfluous detail. It is well-structured and directly to the point, making it highly efficient for both human and AI understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides enough context for the tool's primary function, but it does not mention any return value or output. Given that an output schema exists (context signal indicates true), explaining return values is not required. The description adequately covers the action and purpose, though it omits any edge-case behavior or prerequisites, resulting in a score of 4.
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 fully defines the 'comments' parameter with 'id' and 'content'. The description adds semantic clarity by specifying 'existing' comments and 'new content', which clarify that the 'id' refers to an existing comment and 'content' is the replacement text. This goes beyond the schema's basic definitions, earning a score of 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update multiple existing comments with new content' clearly states the action (update), the target (comments), and the specificity (multiple existing comments with new content). It effectively differentiates from sibling tools like add-comments or find-comments by indicating it modifies existing comments rather than creating or retrieving them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly signals usage for updating existing comments, but it does not explicitly state when to use it versus alternatives. The combination of the verb 'update' and the noun 'comments' makes the purpose clear, and the sibling list includes add-comments, so differentiation is implied. However, no explicit 'use this when' guidance is provided, so a score of 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint and idempotentHint. The description adds no further side-effect details and does not contradict annotations. Since annotations are present, the bar is lower.
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 concise and directly to the point, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential input constraints and does not need to explain return values since an output schema exists. It is complete for the purpose.
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 schema provides descriptions for the array and each field. The description adds the rule to only include fields that need change and reinforces the requirement for type and ID. This adds useful guidance beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update existing reminders) and specifies the required fields (type and ID) and the optional fields (only change needed). It distinguishes from add-reminders and find-reminders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating existing reminders and mentions the required type and ID, but it does not explicitly compare with alternatives like add or find. However, given sibling tools, it is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the tool is known to be a mutating operation. The description adds the key behavioral trait of partial updates ('Send only the fields that change'), which is not captured by annotations. It does not mention specific side effects (e.g., moving a task to a project also lifts it out of sections) but those are described in the parameter schema, so the description adds meaningful value beyond structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the purpose and immediately provides a critical usage hint. Every word earns its place, with no filler or repetition. It is optimally concise for its informational load.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool allows updating up to 25 tasks with many optional fields, the description gives a general overview and a key operational rule (partial updates). The presence of an output schema means return values need no explanation. It does not list all possible field types, but the 'including' phrasing makes that acceptable. It is sufficiently complete for an agent to understand the tool's scope without over-specifying.
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% because each property has its own description, so the schema already fully documents parameters. The tool description provides a high-level summary ('content, dates, priorities, and assignments') that adds grouping context but no additional semantic detail beyond what the schema offers. This meets the baseline for complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update existing tasks') and the scope ('content, dates, priorities, and assignments'), distinguishing it from sibling tools like add-tasks (creation) and complete-tasks (state change). The verb and resource are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Send only the fields that change' provides a concrete usage guideline, and the phrase 'existing tasks' implies this is for modifying existing items, not creating new ones. However, it does not explicitly name alternatives or state when not to use the tool, though the sibling context and the word 'update' make that clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context by explaining how different file types are returned (images inline, text as text, binary as embedded resources), which is valuable beyond the annotations.
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 concise, with two sentences that efficiently convey the purpose, usage, and behavior. No wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is complete enough. It covers the input source, supported file types, and return behavior. The annotations cover safety, so the description doesn't need to repeat that. Minor gap: it doesn't mention error cases (e.g., invalid URL), but this is acceptable for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the fileUrl parameter fully described in the schema. The description reinforces this by explaining the source of the fileUrl ('from a comment's fileAttachment field'), but adds minimal new meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'View a file attachment from a Todoist comment.' It specifies the resource (file attachment) and the action (view), and distinguishes it from siblings by focusing on attachment viewing rather than comment management or other operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: 'Pass the fileUrl from a comment's fileAttachment field.' It explains the prerequisite (obtaining the fileUrl from a comment) and the supported file types, but does not explicitly mention when not to use it or alternatives, though the sibling list suggests other tools for different operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool modifies data (adds comments) and optionally notifies collaborators, which is behavioral information beyond the annotation (readOnlyHint false) and adds context. It does not mention potential side effects like activity logging, but the annotation already implies mutation, and the description covers the main 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 concise, consisting of two clear sentences. It avoids redundancy and conveys the essential information efficiently.
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?
The description does not mention what the tool returns (no output schema is provided) or any error conditions. While it covers the main functionality, the lack of return value information and potential pitfalls leaves some gaps, but it is adequate for a simple add operation.
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 description adds a critical constraint that each comment must specify either taskId or projectId, which is not enforced by the schema. Other parameters like content and notifyUsers are already fully described in the schema, so the description focuses on the key requirement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (add multiple comments), the target (tasks or projects), and the optional notification behavior. It distinguishes from sibling tools like update-comments and find-comments by explicitly using 'add' and mentioning multiple comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about what the tool does and the constraint that each comment must specify either taskId or projectId. However, it does not explicitly mention when to use this tool versus alternatives like update-comments or find-comments, but the intent is implied by the action verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds meaningful context about object types, full-detail retrieval, and optional child inclusion, which complements rather than contradicts the annotations.
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 two front-loaded sentences with no redundancy. Every clause adds value: single object, supported types, ID-based retrieval, and optional child behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-object fetch operation, rich parameter schema, and available output schema, the description plus structured metadata provides complete context for correct tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and parameter descriptions already explain id, type, and includeChildren behavior. The description reinforces includeChildren but does not add meaning materially beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Fetch a single task, project, comment, or section by its ID'), which distinguishes it from sibling find/list tools that search rather than retrieve by known ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance: 'Use this when you have a specific object ID and want to retrieve its full details.' The includeChildren parameter description also steers users away from a speculative find-tasks lookup, though it does not explicitly enumerate exclusions for alternate use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable context about the search behavior (partial, case-insensitive), the 'personal' scope, and what filters are, going beyond simple annotation duplication. No contradictions with annotations.
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?
Two sentences, front-loaded with the action, and the second sentence adds a clear example. Every word earns its place; no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a simple read-only tool: it explains the tool's purpose, the optional parameter behavior, and what filters are. An output schema exists to cover return values, so the description need not explain them.
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 coverage is 100%, so the schema already documents the 'search' parameter. The description echoes the schema (partial, case-insensitive, omission returns all) without adding new parameter-specific information beyond the schema. This meets the baseline for parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('List' or 'search') and resource ('filters'), and distinguishes it from sibling find-* tools by focusing exclusively on filters. It also adds context by explaining what filters are and providing query syntax examples, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use the tool: when you need to list all personal filters or search by name. It provides context about filter semantics, but does not explicitly state when not to use it or mention alternative tools, though the resource-specific nature implies the appropriate scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this is read-only, idempotent, and non-destructive. The description adds useful behavioral context by disclosing that it uses server-side search to avoid fetching all sections, which is not apparent from the annotations.
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 two sentences, front-loaded with the main purpose, and each sentence adds value. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple two-parameter read-only search tool with a complete schema and output schema. The description, combined with the rich annotations and schema, provides enough context for an agent to select and invoke the tool 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 both projectId and searchText fully described in the schema. The description adds no additional parameter-level meaning, so 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search'), identifies the resource ('sections'), and scopes it to a project. It clearly separates this read/search tool from mutation siblings like add-sections and update-sections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: searching for sections within a project by name or criteria. It also adds a rationale for the server-side search behavior, but it does not explicitly state when not to use it or mention alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral detail beyond that: the output is Markdown, and it specifies what content appears in each mode (hierarchy, sections, tasks grouped by sections). There is no contradiction with annotations.
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?
Two sentences communicate the tool's purpose, both usage modes, and output content with no unnecessary words. The most important distinction (projectId provided or not) is front-loaded after a clear one-line summary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, a single optional parameter, strong annotations, and a declared output schema, the description covers everything needed for correct invocation. It explains what happens in both cases and what the response will contain.
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 coverage is 100% and the schema already documents projectId's optionality and its effect on the output. The description essentially restates the schema's parameter meaning without adding new semantics such as format, constraints, or edge cases. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('Markdown overview'), then clearly differentiates two modes based on projectId. It conveys that this is an overview/navigation tool rather than a search or mutation tool, which sets it apart from siblings like find-tasks and find-projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit conditions for both invocation modes: omit projectId for a high-level all-projects overview, or provide it for a detailed project-specific view. It does not name alternative tools or explicitly say when not to use it, but the context is clear enough for an agent to choose appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) establish operation safety profile, and the description complements them by explaining the operational semantics: reordering behavior, the optional parentId move operation, and the special 'root' value. The description adds context about operation ordering (schema says moves happen first, then reorders) that goes beyond the annotations. No contradiction with annotations.
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?
Three sentences, front-loaded with the primary purpose, then conditional instructions for each entity type. Zero wasted words, excellent structure with clear project/section separation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a multi-entity, multi-operation tool, the description covers all key scenarios: reorder projects, move projects (with root handling), and reorder sections. With an output schema present, return values don't need explanation. The sibling table is irrelevant here. Complete enough for an agent to correctly invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value on top by explaining concrete usage scenarios for each parameter combination and the 'root' sentinel. Slightly more detail on how 'items' interacts across multiple reorders could push this to 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource structure ('Reorder sibling projects or sections, and optionally move projects to a new parent') that clearly articulates the tool's dual purpose. It goes beyond the name by explaining the move capability, the 'root' keyword for top-level moves, and explicitly differentiates project behavior from section behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit conditional guidance ('For projects: ... For sections: ...') that tells the agent exactly which parameters to set in each scenario. However, it doesn't reference alternative sibling tools like 'project-move' that might serve a similar purpose, so an explicit when-not-to-use statement would elevate this.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=false, so the description doesn't contradict, but it adds behavioral clarity by specifying personal vs shared label update capabilities. No additional info on side effects or permissions, but adequate for the 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?
Two sentences, front-loaded with the action, no redundant detail. Each word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema covers parameter details well and annotations indicate mutation, the description is sufficient. It doesn't explain return values or errors, but the tool is straightforward. No output schema exists, so not required. Slight improvement could be noting side effects, but it's complete for typical use.
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 schema has extensive descriptions for each parameter, and the description adds interpretive context (e.g., personal labels have color/order/favorite, shared only rename). Schema coverage is high, so baseline 3, but the description adds useful semantic grouping.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates existing labels while distinguishing between personal (by ID) and shared (by name) labels, with specific update capabilities for each. This is specific and differentiates from sibling tools like add-labels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool (updating labels) and clarifies what each label type supports (personal: name, color, order, favorite; shared: only rename). Although it doesn't mention alternatives like add-labels, the guidance is clear for the tool's purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context about the asynchronous nature: 'The analysis may take time to complete.' This goes beyond the annotations by telling the agent to expect a delay and to poll get-project-health for results.
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 two sentences with zero waste. It front-loads the action, then adds usage guidance and a timing caveat. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, non-destructive tool with an output schema and a clear sibling for retrieval, the description covers the trigger condition, the async nature, and the follow-up step. It is complete for the tool's complexity.
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 coverage is 100%: the single parameter projectId is fully described in the schema with 'The ID of the project to analyze. This triggers a new health analysis which may take some time to complete.' The tool description does not add further parameter semantics, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Trigger a new health analysis for a project.' It uses a specific verb (trigger) and resource (project health), distinguishing it from siblings like get-project-health which retrieves results. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'Use this when the health data is stale or you want a fresh assessment.' It also names the alternative follow-up tool: 'use get-project-health afterward to see updated results.' This is strong guidance for selection and invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds explicit user-facing safety context with 'Nothing is modified' and clarifies that the 'url' format avoids returning the whole file. It does not go into edge cases like missing projects or URL expiry, but it is consistent with the annotations.
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 four tight sentences, each earning its place: purpose, use cases, alternative tool guidance, and safety guarantee. It is front-loaded with the core action and avoids filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a read-only export with a robust schema, output schema, and annotations, the description covers the key operational scenarios, format choice, sibling distinction, and non-mutation guarantee. It is complete for an agent to understand what the tool does and when to select it.
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 parameter metadata already explains projectId, format, and useRelativeDates. The description adds cross-tool context for the 'file' format by mentioning handoff to import-project-template, but it does not add significant parameter-level meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Export an existing project as a Todoist template' with the two return modes (CSV or shareable URL). It further distinguishes itself from sibling tools by naming find-tasks and import-project-template in context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'duplicate a project, share its structure, or hand the CSV to import-project-template.' It also gives a clear alternative: 'To read a project rather than export it, use find-tasks instead,' which directly addresses sibling-tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=true, idempotentHint=true), the description adds critical behavioral nuance: explains search scope (all shared projects vs one project), notes partial case-insensitive matching, and importantly clarifies that an empty result doesn't mean the user doesn't exist in Todoist—just not a collaborator. This is valuable context for interpreting results.
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 compact—two sentences plus inline parameter explanations—and front-loads the purpose and usage. Every sentence adds value, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only lookup tool with 2 optional parameters, the description covers usage, scope, edge cases (empty result meaning), and matching behavior. An output schema exists, so return format is covered. Given tool complexity and rich annotations, this is complete.
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 input schema already fully describes both parameters (projectId, searchTerm) with the same details the description provides. The description adds no new meaning beyond the schema, hence baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds Todoist users by name or email to look up their user ID, with concrete examples ('find Carrie's user ID', 'who is Ernesto'). It distinguishes from sibling find-tasks/find-projects by being specifically for people/collaborators.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance ('Use this whenever the user asks to find, look up, or identify a person') and clarifies behavior with/without projectId. It doesn't mention when not to use or name alternatives, but the context is clear enough for a single-purpose lookup tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive. The description does not contradict these and adds practical usage context (e.g., setting responsibleUser to current user). It lacks an explicit statement about no side effects, but annotations cover that, so slight extra info is beneficial.
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?
Description is succinct and well-structured, with no redundant or fluff content. Each sentence adds value, covering usage distinctions and defaults clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's many filtering options, the description provides essential context for understanding its primary use case and key differentiators. It does not enumerate every filter, but those are fully defined in the schema, making the overall context complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 12 parameters with detailed descriptions, including patterns, defaults, and enums. The tool description adds extra guidance on responsibleUser usage and reinforces defaults, which supplements rather than repeats, giving a 4 over the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool's function: 'Get completed tasks in a date range' and distinguishes it from find-activity which reports completion events, including recurring instances. This precise scoping makes the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly directs users to use find-activity for 'what did I complete/get done' queries, and explains default date windows and responsibleUser behavior. This gives strong guidance on when to choose this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint: true, but the description adds crucial context by explaining that recurrence patterns are preserved and only the date is changed. It also clarifies that a date-only input preserves existing time. This goes beyond the annotations, though it doesn't mention other potential side effects or limitations.
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—two sentences that front-load the core purpose, then provide differentiation and usage. Every sentence earns its place with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter with full schema coverage), an output schema, and clear annotations, the description sufficiently covers the behavioral contract. It doesn't discuss error cases or prerequisites, but those are not critical for this type of operation. The key distinction from update-tasks is well-handled.
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 schema already documents the 'tasks' parameter thoroughly with 100% coverage. The description enhances this by explaining the nuance that a date-only value preserves an existing specific time, and directly ties the date parameter to the recurrence-preservation behavior. This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: reschedule tasks to new dates while preserving recurring schedules. It explicitly contrasts with the sibling tool update-tasks, specifying that this tool only changes the date and keeps recurrence patterns intact, making it distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on when to use this tool vs. update-tasks: 'Use this when moving recurring tasks to a different date without altering their repeat pattern.' This directly addresses usage context and alternatives, leaving no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the annotations: it specifies the tool reports counts, streaks, and karma only, never the tasks themselves. This is valuable because it clarifies the output scope. The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well-covered. The description could add more about the output structure, but the output schema exists to cover that.
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 concise and well-structured. It front-loads the core purpose, then lists the specific data types, and ends with a clear exclusion and pointer to an alternative. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has zero parameters, a rich output schema, and strong annotations (readOnly, idempotent, non-destructive), the description is complete. It covers what the tool does, what it returns, and when to use an alternative. The output schema handles return value details, so the description doesn't need to enumerate them.
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 zero parameters, and the schema description coverage is 100% (vacuously true). The description adds value by explaining what the tool returns (daily/weekly breakdowns, streaks, karma trends), which is the main semantic content. Since there are no parameters to document, a baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: retrieving comprehensive productivity statistics including daily/weekly completion breakdowns, goal streaks, karma score and trends, and historical karma data. It explicitly distinguishes itself from sibling tools by noting it reports counts, streaks, and karma only, never tasks themselves, and directs users to find-activity for task-level details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it is useful for productivity analysis and tracking goal progress, and it explicitly states when NOT to use it (for 'what did I complete' queries, use find-activity instead). This clear differentiation from the sibling tool find-activity is excellent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare write semantics (readOnlyHint: false); the description adds critical context beyond that: "This writes immediately and cannot be undone" and the warning to only run against projects the user explicitly named. The irreversibility warning and the distinction between gallery vs. personal template permissions in the schema enrich the annotation-only picture. No contradiction with annotations.
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?
Four sentences, zero filler. The purpose is front-loaded, followed by sourcing options, workflow sequencing, and a critical irreversibility warning — every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter import tool with 100% schema coverage and an output schema present, the description covers all key operational concerns: merge behavior, input sourcing, project-creation prerequisite, and irreversibility risk. Nothing material is left unaddressed for an agent to execute correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the rich per-parameter docs carry the burden. The description adds only a high-level summary ("by template ID/URL or by passing CSV content") that maps to templateId vs csvFileContent, reinforcing the exclusive-or relationship already documented in the schema. This is a solid baseline-3 case — no new syntactic meaning added beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Starts with the specific verb+resource+scope "Import a template into an existing project, adding its tasks, sections and comments to whatever is already there," making the merge semantics explicit. It distinguishes itself from sibling `export-project-template` and `add-projects` by clarifying this is for existing projects only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit workflow guidance: "To start a new project from a template, create the project with add-projects first, then import into it" names the exact alternative tool and sequencing. The safety rule "only run it against a project the user named" provides a clear when-to-run criterion. Only minor gap is not naming a 'when not to use' beyond the new-project case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, so description doesn't need to repeat that. It adds valuable behavioral details: that archived projects can be deleted via delete-object, and that pagination is ignored in certain modes. However, it doesn't explicitly state that returns are read-only beyond annotations, but that's covered. Also, it notes that archivedStatus 'all' ignores pagination, which is useful. Minor gap: no mention of rate limits or auth, but not critical. A 4 is appropriate given the good annotation coverage and useful edge-case note.
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?
Description is concise, three sentences, front-loaded with main purpose. Each sentence adds new information: purpose and default, pagination behavior, and the isArchived field/deletion note. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list/search tool with rich schema (100% coverage) and output schema present, description covers all key aspects: default filtering, pagination behavior, wildcard search, and archived status handling. It even links to deletion, which is helpful. Given complexity, it is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds significant extra meaning beyond schema: it explains the interaction between archivedStatus and pagination, and clarifies that archivedStatus 'all' can be used to include archived projectsament. It also mentions isArchived field and deletion path, enriching parameter semantics beyond raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists or searches projects by name, with a specific verb 'find' and resource 'projects', and differentiates from siblings like find-tasks and find-sections by focusing on projects. Also explains default active-only behavior, adding specific scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use it: to list all projects or search by name. Mentions default behavior (active only), when to use archivedStatus, and how pagination behaves in different modes. Names alternative deletion via delete-object for archived projects, providing usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by detailing the pagination behavior, search handling (ignoring limit/cursor), and the distinction between personal and shared label metadata. It also discloses that shared labels lack IDs and metadata, which is crucial for downstream usage.
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 well-structured, starting with the general purpose, then explaining the two types of labels, and then the two behavioral modes. It is dense but clear, with no fluff or redundant phrases, and every sentence adds distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (two label types, pagination, search behavior), the description covers all major aspects: what is returned, how pagination works, how search affects results, and the metadata difference. Combined with the rich annotations, it is complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the parameters well (100% coverage), so the description adds context beyond the schema by explaining how they interact: limit/cursor are ignored during search, and searchText supports wildcards. That said, it doesn't add unique high-value info beyond what the schema already describes, but it does contextualize usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool lists labels, distinguishing personal labels vs shared labels, making the purpose is clear and distinct from siblings like find-labels' siblings like find-tasks or find-projects. It specifies the resource (labels) and the action (list/search) with precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains when to use the tool (listing labels, searching by name) and contrasts with alternatives implicitly: by noting shared labels are returned as names only. The description even notes the difference in behavior when searching vs not, guiding the agent on parameter usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the readOnly/idempotent annotations by noting that activity history availability and retention depend on the user plan, adding important limitations.
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 concise, well-structured, and every sentence provides useful information without redundancy, making it efficient for an AI agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage examples, filtering logic, and plan limitations, and since an output schema exists, it does not need to elaborate on return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema already describes each parameter, the description adds valuable context on how to combine parameters to achieve specific queries, such as filtering by user or object type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves activity logs for monitoring and audit, distinguishing it from other find-* tools by focusing on activity events and providing specific filtering guidance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains when and how to use the tool, including concrete examples such as querying completed tasks with objectType, eventType, and date ranges, and for first-person questions using initiatorId.
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/Doist/todoist-mcp/badges/card.svg)](https://glama.ai/mcp/servers/Doist/todoist-mcp)

Score Badge

Copy to your README.md:

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

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