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.

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.

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.

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.

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.

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.

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

The description only states what the tool does and does not disclose side effects, required permissions, rate limits, or response behavior. The annotations indicate readOnlyHint: false (write operation), but the description adds no extra behavioral context. For a write operation, an agent would benefit from knowing what the response contains or any side effects, which are not mentioned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that conveys the essential purpose without any fluff or redundant information. It is well-structured and immediately understandable.

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

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

The description provides enough context for an agent to know that this tool creates personal filters using query syntax. It implies that filters are custom views. However, it does not mention any prerequisites, limits (e.g., maximum number of filters), or what the response looks like. But for a simple add operation, the given information is largely sufficient. The presence of a full output schema (not shown) may fill some gaps, but the description alone is mostly complete.

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

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

The input schema provides comprehensive descriptions for all parameters (name, color, query, isFavorite, description) with examples and valid values. The tool description itself adds no additional meaning about parameters. Since the schema already covers semantics fully, the description does not need to repeat them, but it also does not enrich them further. This is an adequate but not outstanding score.

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

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

The description clearly states the tool's action: 'Add one or more new personal filters.' It specifies the resource (personal filters) and the verb (Add), making it obvious this is a creation operation. It also briefly explains what filters are, which helps an agent understand the domain.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description is explicit about creating new filters (not updating existing ones) by using the word 'new.' While it doesn't directly mention alternative tools like 'update-filters' or 'find-filters,' the context from the sibling list and the clear 'Add' verb imply when to use this tool. The description could be slightly more explicit about not using it for modifications, but it is sufficiently clear for an agent to decide.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations already communicate that the operation is mutating, non-idempotent, and not destructive. The description adds a useful behavioral constraint around assignment to project collaborators, but does not go further into side effects, validation, or failure modes. This is acceptable given the annotation coverage, though not particularly rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, tightly worded sentence that front-loads the core action and target, then adds the most relevant capability. There is no filler or repetition of what the schema already states.

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

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

The tool has one parameter, a fully documented nested schema, an output schema, and annotations covering mutation behavior. The description's simple statement of targets and assignment support is sufficient context for an agent to invoke it correctly without needing information already present in the schema.

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

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

Schema description coverage is 100%, so the schema already documents all fields thoroughly, including content requirements, due dates, duration formats, and assignment details. The tool description adds no parameter-level semantics beyond the general mention of assignment support, which matches the baseline for high schema coverage.

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

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

The description clearly states a specific verb ('Add'), a resource ('tasks'), and the allowed targets ('project, section, or parent'). It also adds a distinguishing capability ('assignment to project collaborators'), making it easy to tell apart from sibling tools like update-tasks or complete-tasks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description establishes a clear context for use: creating one or more tasks in a Todoist project, section, or as subtasks. It does not explicitly mention alternatives or exclusions, but the action is unambiguous and well differentiated from siblings 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context by stating that the tool returns the full contents and explicitly noting that comments are not included and should be fetched separately via find-comments.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The core action is front-loaded, followed by the required ID format and a concise caveat about comments. Every sentence earns its place.

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

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

Given the single parameter, robust annotations, and an existing output schema, the description covers everything needed to invoke the tool correctly: what it fetches, the ID format, and what it does not return. No critical information is missing.

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

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

Schema description coverage is 100%, and the single 'id' parameter is already documented with the exact format. The tool description repeats that format rather than adding new semantic meaning, so it meets the baseline without exceeding it.

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

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

The description states a specific verb ('Fetch') and resource ('full contents of a task or project by its ID'), and gives the exact ID formats. This makes it clearly distinct from the many sibling find* and search tools, which are for discovery rather than retrieval 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.

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

It clearly conveys that the tool is for fetching a single task or project via a prefixed ID, and it explicitly directs comment retrieval to find-comments. It does not explicitly enumerate alternatives like find-tasks or find-projects, but the 'by its ID' framing provides enough contextual guidance.

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

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 useful behavioral context by noting that includeChildren retrieves direct subtasks or sub-projects, which goes beyond the basic annotations. No contradiction with annotations exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three short sentences with no filler. It front-loads the core action, immediately provides the usage context, and then covers the optional parameter. Every sentence earns its place.

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

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

The description is complete for a read-only single-object fetch tool. Combined with rich schema descriptions, annotations, and an output schema, an agent has everything needed to select and invoke the tool correctly without ambiguity.

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

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

Schema description coverage is 100%, so the schema already fully documents id, type, and includeChildren. The description reinforces the parameter usage with 'by its ID' and 'direct subtasks or sub-projects,' but it does not add meaning substantially beyond the schema's existing parameter descriptions. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Fetch') and names the exact resources ('task, project, comment, or section') plus the key selector ('by its ID'). It clearly distinguishes this single-object fetch tool from sibling find/search tools by emphasizing the need for a specific object ID.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description explicitly states when to use the tool: 'Use this when you have a specific object ID and want to retrieve its full details.' It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to route to this tool instead of a find/search tool.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context beyond that: the 7-day default window, all-collaborator scope by default, and the exclusion of recurring-task occurrences. This addresses likely agent misconceptions about the tool's results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences deliver the essential scoping, the alternative tool, and key defaults without redundancy. The most important information (what the tool does) is front-loaded, and every sentence earns its place. No filler or repetition.

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

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

For a 12-parameter tool with a rich schema and output schema, the description covers the key decision points: purpose, alternative, date-range defaults, collaborator handling, and responsibleUser requirement. It does not explain pagination or filter specifics, but those are fully documented in the schema and annotations, so the description is sufficiently complete for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats default-window information already in the schema and mentions responsibleUser for person-specific queries, which adds a small usage hint. However, it does not meaningfully compensate beyond what the schema provides, so 3 is appropriate.

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

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

The description opens with 'Get completed tasks in a date range,' naming the verb, resource, and scope. It further distinguishes from find-activity by noting that find-activity reports completion events including every recurring task occurrence, which this tool does not. This makes the tool's unique role clear relative to siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly instructs when to use find-activity instead ('For "what did I complete/get done" questions'), and clarifies that this tool excludes recurring-task occurrences. It also states date-range defaults and collaborator behavior, plus the requirement for responsibleUser in person-specific queries, leaving little ambiguity about selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral scope beyond annotations by specifying 'personal filters' and explaining the filter concept, which helps the agent understand what data will be returned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler: the primary operation is front-loaded, and the clarifying example is compact and informative. Every sentence earns its place.

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

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

For a low-complexity, single-optional-parameter read-only tool with a full output schema, the description is complete. It explains the domain concept, the two modes of invocation, and the scope without requiring additional context.

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

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

Schema description coverage is 100%, so the schema fully documents the 'search' parameter including partial and case-insensitive matching and the omitted-parameter behavior. The description only restates 'by name' and adds no new parameter semantics beyond the schema.

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

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

The description uses a specific verb ('List'/'search') with a clear resource ('filters') and scope ('personal'). It also explains what a filter is with concrete query syntax examples, making the tool's purpose unmistakable and distinguishable from task or project finders.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description clearly conveys the two usage modes: list all filters or search by name. It does not explicitly name alternatives or exclusions, but the definition of filters as saved custom views gives enough context for an agent to know when this tool applies versus task/project search tools.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 covered. The description adds the mandatory-filter behavior, but does not disclose what happens when no filter is passed or any response/pagination behavior; the output schema presumably covers return structure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The entire description is a single, dense sentence that front-loads the action and resource, lists the relevant filter dimensions, and states the key constraint. There is no redundancy or filler.

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

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

Given the tool's 12 parameters, a fully populated schema, annotations, and an output schema, the description provides a sufficient high-level mental model and the one critical cross-parameter constraint. It is slightly incomplete only because it does not address sibling-tool differentiation or when an alternative should be used.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by stating the at-least-one-filter invariant, which is not enforced in the schema, and by grouping the 12 parameters into meaningful filter categories that help an agent reason about valid calls.

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

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

The description opens with a specific verb and resource — 'Find tasks by...' — and enumerates the many filter dimensions (text, project/section/parent, responsible user, labels, raw filter, saved filter), making its scope immediately clear. It does not explicitly distinguish itself from siblings like find-tasks-by-date or find-completed-tasks, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The only usage guidance is the constraint 'At least one filter must be provided,' which is a call requirement, not a when-to-use guideline. With close siblings such as find-tasks-by-date and find-completed-tasks present, the description gives no direction on when to choose this tool over an alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable behavioral specifics beyond annotations: the semantics of 'today' with overdue inclusion and the default user filtering behavior. No contradiction exists between the description 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences with no filler. The core action is stated first, and the second sentence packs in two behavior-affecting defaults. It could be slightly more specific about scope but is otherwise well-sized.

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

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

With a rich input schema (100% coverage), output schema, and safety annotations, the description does not need to cover return values or every parameter. It provides the most non-obvious defaults that affect results. The remaining gaps, such as pagination or label behavior, are already handled by the schema and tool output.

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

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

Schema description coverage is 100%, so the schema already documents all parameters and defaults. The description highlights startDate and responsibleUserFiltering, but these details are already present in the schema property descriptions. It does not add new parameter meaning beyond what the schema already provides.

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

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

The description states a clear verb and resource: 'Get tasks by date range.' It conveys the tool's scope precisely. However, it does not explicitly differentiate from sibling tools like find-tasks or find-completed-tasks, relying on the title and schema for that distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description gives important usage context by noting that startDate='today' includes overdue items and that the default responsibleUserFiltering='unassignedOrMe' excludes others' tasks. This helps an agent decide whether this tool fits the request or whether parameters need to be changed. It does not explicitly state when to prefer sibling tools or provide negative usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value beyond annotations by disclosing the Markdown return format, the parameter-dependent mode switch, the exclusion of tasks in the account-wide view, and section grouping behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with zero waste. The primary deliverable (Markdown overview) is front-loaded, and the mode-dependent behavior is packed into a compact second sentence that covers both call variants.

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

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

For a read-only, single-optional-parameter tool with annotations covering safety and an output schema present, the description fully covers invocation modes, output format, and scope. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% — the schema already documents projectId, the 'inbox' special value, and the two behavioral outcomes. The description reinforces this but adds minimal new meaning beyond the schema's own parameter documentation.

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

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

Description states a specific verb and resource ('Get a Markdown overview') and precisely distinguishes the two invocation modes: account structure without a projectId versus tasks grouped by section with one. This clearly differentiates it from siblings like find-tasks, find-projects, and 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.

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

The description gives explicit when-to-use conditions for both modes: omit projectId for navigation structure only, or pass projectId/'inbox' to get tasks grouped by section. It implies the alternative use cases (navigating vs. retrieving tasks) but does not name sibling tools explicitly or state when not to use this tool.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Adds important non-obvious behavior beyond the annotations: writes immediately, cannot be undone, and merges into existing project content. It also clarifies template source limitations (gallery vs. personal templates). This does not contradict destructiveHint=false because the operation adds rather than destroys existing data, though it is irreversible.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: the primary behavior, the sourcing options, and the new-project workflow plus safety warning. The most important information is front-loaded before the cautionary guidance.

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

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

Provides the essential context for a mutating import operation: merge semantics, source options, workflow for new projects, and irreversibility. Since an output schema exists, the description doesn't need to explain return values, and nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the input schema already documents projectId, templateId, csvFileContent, and locale thoroughly. The description repeats the ID/URL/CSV distinction and the mutual exclusivity, but adds little meaning beyond what the schema already provides.

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

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

States a specific verb ('import') with a clear resource (template) and target (existing project), and explains the merge semantics by listing what gets added: tasks, sections, and comments. It distinguishes itself from siblings like export-project-template and add-projects by focusing on importing into an existing project.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly names the workflow for new projects: create the project with add-projects first, then import. It also tells the agent when to use template ID/URL versus CSV content from export-project-template, and warns to only run it against a project the user named.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations already mark destructiveHint=true, and the description adds meaningful behavioral context: it changes only the date, preserves recurrence patterns, and does not replace the entire due string. This goes beyond what annotations convey, though it does not discuss response details or error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: main action, contrast with the sibling tool, and explicit usage direction. Front-loaded and free of filler.

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

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

Given the output schema exists, return values need no explanation. The description covers purpose, when to use it, the alternative to avoid, and the key behavioral guarantee of preserving recurrence. This is complete for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, and the input schema already documents the tasks array, id, and date format including time preservation behavior. The description contributes the recurrence-preservation nuance but does not add substantial parameter-level meaning beyond the schema.

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

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

States a specific verb and resource: 'Reschedule tasks to new dates while preserving recurring schedules.' It directly distinguishes itself from update-tasks, making the tool's scope unmistakable even without inspecting the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

Explicitly provides when-to-use guidance: 'Use this when moving recurring tasks to a different date without altering their repeat pattern.' It also names the alternative (update-tasks) and explains why that alternative can be harmful (wipes recurrence), leaving no ambiguity about selection.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

The annotations already indicate destructiveHint: true and readOnlyHint: false, so the description does not need to restate that. However, it adds no extra behavioral detail beyond the implied mutation of filters, such as whether updates are partial or require all fields, or what happens to unspecified properties.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that directly conveys the tool's purpose without redundant wording. It is front-loaded with the action and subject, making it easy to parse and understand at a glance.

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

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

For a mutating operation, the description covers the fundamental action but omits contextual details such as the output/response format (despite an output schema being present) and potential error conditions (e.g., nonexistent filter IDs). While annotations convey destructive nature, the lack of information about results or edge cases leaves the agent somewhat underinformed.

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

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

The input schema provides thorough descriptions for the single 'filters' parameter and each nested property (id, color, query, etc.), covering 100% of the schema. The tool description itself adds no additional semantic meaning beyond what the schema already offers, so it relies on the schema's detail.

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

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

The description clearly states a specific action ('Update') on a distinct resource ('existing personal filters') and indicates the operation modifies with 'new values.' It differentiates itself from sibling tools like add-filters and find-filters by explicitly targeting existing filters for modification.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description does not provide any guidance on when to use this tool versus alternatives. It lacks explicit mention of scenarios where updating is appropriate or when other operations like adding or finding filters would be preferred, leaving usage decisions to the agent's inference.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations already signal a mutating and destructive operation (destructiveHint true, readOnlyHint false), so the description only needs to add context beyond that. It adds the useful partial-update behavior, but it does not disclose side effects such as project or section moves lifting a task out from under its parent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences with no filler: purpose is front-loaded and the key usage rule immediately follows. Every word earns its place.

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

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

For a single-parameter batch tool with exhaustive schema documentation, an output schema, and safety annotations already present, the description carries the core guidance efficiently. It lacks explicit sibling routing and side-effect warnings, but those are partially covered by schema descriptions and sibling tool names.

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

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

The tasks parameter is fully documented by the schema (100% coverage) with per-field descriptions for id, content, dueString, priority, labels, and more. The description adds no parameter-level meaning beyond what the schema already provides, so the baseline score applies.

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

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

The description names the exact operation (update), the resource (existing tasks), and the main updatable areas (content, dates, priorities, assignments). The phrase 'existing tasks' distinguishes it from add-tasks, and the resource name separates it from sibling tools like update-reminders and update-labels.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

It gives clear context by saying the tool updates existing tasks and provides a concrete invocation norm: 'Send only the fields that change.' However, it does not explicitly name alternatives or exclusions, so it falls just short of full routing guidance.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.