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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive, open-world write, so the safety profile is covered. The description adds that the tool operates in batch and that notification is opt-in, which is useful context. What it omits is meaningful for a batch mutation: no statement about partial-failure semantics, duplicate handling, or permission requirements.

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

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

Two short sentences, zero filler, with the batch scope and the per-item ID constraint front-loaded. Each sentence carries 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description covers the batch shape and the ID constraint. It is only marginally incomplete in not resolving whether both taskId and projectId may be supplied on the same comment.

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 would be 3. The description genuinely adds meaning by stating that each comment must carry either taskId or projectId — a mutual-requirement constraint the schema does not encode (neither field is individually required and there is no oneOf). That is real value beyond the structured 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 ('Add') and resource ('comments') with the batch aspect ('multiple') and the two valid parent resources (tasks or projects) made explicit. It is clearly distinguishable in verb from siblings like find-comments and update-comments, though it never names them directly.

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?

'Optionally notifying collaborators' and 'Each comment must specify either taskId or projectId' give preconditions for a valid call. However, there is no explicit guidance on when to use this versus update-comments (editing an existing comment) or find-comments, leaving the agent to infer the choice from the verb alone.

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 this as a non-read-only, non-idempotent, non-destructive mutation. The description adds useful domain context that filters are personal saved views using query syntax, but it does not disclose duplicate-name behavior, validation failures, or what is returned.

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

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

The description is two concise sentences with no wasted wording. The primary action is front-loaded, followed by a useful clarification of what a filter is.

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 operation with full schema coverage, annotations, and an output schema, the description is largely complete. A minor gap is that it does not mention duplicate handling or error behavior, but nothing essential for 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 schema already documents the filters array, required name and query fields, color, favorite status, and description. The description only adds that one or more filters are accepted and that queries use syntax, matching rather than exceeding the schema baseline.

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

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

The description states a specific verb and resource: adding new personal filters, described as saved custom views using query syntax. It distinguishes creation from updating or finding filters only implicitly through 'new', but an agent can tell 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?

Usage is implied: use this when creating one or more new personal filters. However, the description does not explicitly contrast with update-filters or find-filters, nor does it state conditions such as handling existing filters.

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 readOnly=false, destructive=false and idempotent=false, so the safety profile is covered. The description adds only that labels are 'personal', and says nothing about duplicate-name behavior, partial-batch failure, or whether later calls overwrite prior labels — gaps that matter for a non-idempotent create.

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 with zero waste. It is efficiently written, though its brevity leaves real questions unanswered rather than being a model of structured 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?

With rich schema coverage, full annotations and an output schema, the definition is minimally sufficient to invoke the tool. It is incomplete on batch semantics — whether one invalid or duplicate label fails the whole array — which is the main thing an agent can't derive from structured fields.

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 nested label object documents name, color (including fallback to charcoal), order and isFavorite in detail. The description contributes nothing beyond the schema, 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?

States a specific verb (add) and resource (new personal labels) with a scope qualifier ('personal') that hints at non-shared labels. It does not explicitly distinguish itself from update-labels or add-projects, so an agent must infer the boundary from the name alone.

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

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

There is no when-to-use guidance, no exclusion against update-labels for existing labels, and no mention of what happens if a label name already exists. The only implicit signal is 'new', which the agent must interpret on its own.

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 disclose that this is a non-read-only, non-idempotent, non-destructive mutation. The description adds no behavioral context such as duplicate handling, required permissions, or side effects beyond what annotations provide.

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 single sentence is front-loaded and free of fluff, but it is severely under-specified for a creation tool with a rich nested schema. Brevity here reflects omission rather than optimized 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?

The schema and annotations cover most invocation details, and the output schema means return values need not be described. However, the description lacks usage and behavioral context that would help an agent choose and call this tool confidently.

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 nested project fields are fully documented in the schema. The description adds no parameter meaning beyond the schema, 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 and resource: 'Add one or more new projects.' It clearly conveys project creation and batch scope, but does not differentiate from siblings such as update-projects or add-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 provides no when-to-use guidance, prerequisites, or alternatives. It does not mention when to choose add-projects over update-projects or find-projects.

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, idempotentHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral default — reminders notify their creator unless notifyUser says otherwise — but says nothing about duplicate handling or whether re-adding the same reminder is safe, which matters given idempotentHint=false.

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 tight sentences, front-loaded with the action and the type taxonomy, then the taskId requirement, then the recipient default. Nothing is wasted and no sentence repeats another.

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 an output schema, full annotation coverage, and a rich oneOf schema, the description supplies what structured fields cannot: the type taxonomy framing and the default recipient rule. The remaining gap is routing relative to update-reminders, which the sibling list makes relevant.

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 taskId, minuteOffset, due, locLat/locLong, service, etc. The description only restates the type taxonomy at a high level ("relative" minutes before due, "absolute" specific date/time, "location" geofence), adding framing but no field-level detail 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+resource ("Add reminders to tasks") and enumerates the three supported reminder types, so an agent knows exactly what the tool produces. It does not, however, differentiate itself from the sibling update-reminders or find-reminders, which keeps it 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?

"Each reminder must specify a taskId" and the type breakdown imply when the tool applies (creating new reminders on existing tasks), but there is no explicit guidance on when to use this versus update-reminders/find-reminders, nor any stated prerequisites such as collaboration on the task's project.

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, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not say what happens on duplicate section names (relevant given idempotentHint=false), whether the batch is atomic, or whether permissions are required.

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 with zero filler. It is arguably too terse for the tool's complexity, but that gap is captured under contextual completeness rather than counted as verbosity here.

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?

Output schema and rich annotations reduce the burden, and the schema fully documents the single nested parameter. Still missing is anything about duplicate handling, batch failure semantics, or ordering of created sections, which matters for a non-idempotent create 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%, with nested field descriptions for name, projectId (including the 'inbox' sentinel) and description already documented. The description contributes no parameter meaning beyond the schema, so the baseline 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?

States a specific verb and resource ('Add ... new sections to projects') and makes the batch nature explicit with 'one or more.' It is distinguishable from update-sections/find-sections by convention, but the description never names them, so sibling differentiation is only implicit.

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 when-to-use guidance, no exclusions, no mention of update-sections as the alternative for modifying existing sections. The only signal is the verb 'Add', which the agent must infer from the name.

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=false, so the mutation profile is covered. The description's only added claim, 'supports assignment to project collaborators', is already documented on the responsibleUser property, and it says nothing about batch partial-failure behavior or the collaborator-membership prerequisite beyond what the schema states.

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

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

Two compact sentences with the verb and targets front-loaded, no filler. It is efficient but so terse that it barely engages with a fairly complex batch payload.

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?

An output schema and full parameter documentation exist, so return values need not be explained. However, for a non-idempotent batch mutation this description omits the 25-task cap, duplicate-risk on retry, and what happens if only some tasks in the array fail – gaps that matter 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% and the nested task properties are richly documented, so the baseline of 3 applies. The description adds only the vague 'one or more' framing and the container list, without any syntax, ordering, or required-field guidance 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 (add) and resource (tasks) plus the three target containers (project, section, parent), so an agent can distinguish it from update-tasks or add-sections. It stops short of explicitly naming the sibling it supersedes 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 phrase 'Add one or more tasks to a project, section, or parent' implies the usage context (task creation, batch-capable), but it never states when to prefer this over update-tasks or when to use add-sections instead. Usage is inferable rather than explained.

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=false and idempotentHint=true, so the safety profile is partially covered; the description adds the non-obvious facts that the source project is not modified and that the 'url' format uploads a copy returning a publicly openable link. This is real value beyond annotations, though permission requirements and size limits are left implicit (large-project guidance lives in the schema).

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 tight sentences, front-loaded with the action and its outputs, then use cases, then the sibling pointer, then the side-effect caveat. No repeated 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?

With an output schema present, return values needn't be explained, and the description still covers formats, side effects, and the correct sibling for read-only needs. Minor gap: nothing about required permissions or workspace scope for the upload path, which matters for an open-world 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% and the format enum is fully documented in the schema, including the large-project rationale. The description only echoes that two formats exist and says nothing about useRelativeDates, so it adds no semantics beyond the schema — baseline 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?

Opens with a specific verb+resource ('Export an existing project as a Todoist template') and immediately names the two output forms (CSV content or shareable URL). An agent can distinguish this from import-project-template and find-tasks without opening any 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?

Gives concrete use cases (duplicate a project, share its structure, hand CSV to import-project-template) and an explicit exclusion: 'To read a project rather than export it, use find-tasks instead — it returns structured tasks rather than raw CSV.' Both when-to-use and the named alternative are present.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only that returning an object yields "full details"; it says nothing about behavior for an unknown ID, a mismatched type, or permission failures. 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?

Three short sentences, front-loaded with the resource scope, then the usage condition, then the optional flag. Nothing is redundant or padded.

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 an output schema present, return-value explanation is unnecessary, and annotations plus 100% schema coverage handle most remaining gaps. The description covers what matters for correct invocation; only error/not-found behavior is unaddressed, which is minor for a pure 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?

Schema description coverage is 100%, so the schema already documents all three parameters, including the detailed includeChildren semantics (childCount, compact list, ignored for comments/sections). The description's includeChildren sentence mostly restates the schema, so baseline 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 gives a specific verb ("Fetch") and enumerates the exact resources (task, project, comment, section) plus the lookup key (ID). It implicitly separates itself from the find-* siblings by framing the tool around a known ID and full detail retrieval, but it never names an alternative outright.

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?

"Use this when you have a specific object ID and want to retrieve its full details" is a clear triggering condition that naturally excludes search-style tools. It lacks an explicit when-not or a named alternative such as find-tasks/find-projects, which keeps it below a 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds non-obvious behavior the annotations cannot: results span all users unless initiatorId is set, and history availability/retention vary by plan. Useful additions; pagination flow and result volume are left to the schema.

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?

Front-loaded with the core purpose, then query recipes, then the caveat — a sensible ordering. The sentence "Track task completions, updates, deletions, project changes, and more with flexible filtering" is largely filler that restates earlier 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?

With an output schema present and 100% param coverage, the description only needs to supply selection logic and gotchas, which it does (default scope, initiatorId rule, retention). Pagination behavior across the cursor and how large histories are returned is the only notable omission.

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 baseline would be 3, but the description adds real semantic value on top: the initiatorId/first-person rule, the objectType+eventType combination that answers completion questions, and the default all-users scope. It does not add detail on limit/cursor or the date range semantics beyond what the schema documents.

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?

Specific verb+resource ("Retrieve activity logs") plus an explicit purpose (monitor and audit changes in Todoist) and a scope statement (all users by default). It distinguishes its coverage (completions, updates, deletions, project changes) but never names the closest sibling, find-completed-tasks, so an agent must reason about overlap itself.

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?

Very clear situational routing: objectType "task" + eventType "completed" + dateFrom/dateTo for period-completion questions, and initiatorId for first-person questions, with the failure mode spelled out ("or the answer includes collaborators' completions"). It stops short of naming alternatives or stating when to prefer find-completed-tasks instead.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the recurring-task limitation, the 7-day default window behavior, and that all collaborators are included by default. It stops short of describing pagination or result ordering, so a 4 rather than 5.

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?

Front-loads purpose, then sibling routing, then key parameter defaults — a sensible order with no wasted sentences. It is dense but each sentence carries information; minor compression could still improve readability.

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 an output schema and full annotations, the description covers purpose, the critical alternative, defaults, and the collaborator/responsibleUser scoping rule. Combined with the rich schema and output schema, an agent has everything needed to call 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?

Schema coverage is 100%, so the baseline is 3; the description earns above that by clarifying the since/until default window and the responsibleUser semantics (defaults to all collaborators, set to current user for personal reports). It doesn't elaborate on getBy, limit, or labels beyond the schema, so not a full 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?

States a specific verb (get) and resource (completed tasks) with explicit scope (date range), and immediately distinguishes itself from find-activity. An agent can tell exactly what this returns versus the sibling without opening either 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 routes 'what did I complete' questions to find-activity and explains the recurring-task caveat that differentiates the two. It also tells the agent that person-specific queries require responsibleUser, giving concrete when-to-use/when-not 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=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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful fact that a taskId lookup returns both time-based and location reminders, but says nothing about result volume, pagination, or behavior when no reminder matches.

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

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

Two short clauses, front-loaded with the primary taskId use case followed by the single-item modes. No filler; the only mild redundancy is repeating the parameter-level distinctions already in the schema.

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 full output schema present and 100% parameter description coverage, the description need not explain return values, and it correctly frames the two access patterns. Missing only the mutual exclusivity of the three ID parameters and any empty-result behavior.

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 each parameter already carries its own description that essentially duplicates the description text ('Get a specific time-based reminder ... by its ID'). The description adds no format, prefix, or ID-provenance information beyond the schema, so baseline 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?

States a specific verb (find) and resource (reminders), and enumerates the two lookup modes: by task ID (returning all types) or by a specific reminder ID. It does not name or contrast any sibling (e.g. find-tasks, update-reminders), so it stops short of full differentiation.

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 mode-selection guidance (reminderId for time-based, locationReminderId for location), which is real usage direction. But there is no guidance on when to reach for this tool versus add-reminders/update-reminders or find-tasks, and no note that the three parameters are mutually exclusive alternatives.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds the non-obvious behavioral constraint that at least one filter must be supplied, but it does not add further context about pagination, filter-combination behavior, or permission requirements beyond what the schema provides.

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 plus a brief mandatory-filter constraint. It communicates the core capability and the key validation rule without 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?

Given rich annotations, 100% schema coverage, and an output schema, the description covers the essential purpose and the at-least-one-filter rule. It is nearly complete, though it could better route the agent among its date-oriented and completed-task siblings.

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 all 12 parameters in detail. The description lists the filtering modes but adds no substantive parameter semantics beyond what is already present in 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 states a clear verb ('Find') and resource ('tasks') and enumerates the supported filtering modes: text search, project/section/parent, responsible user, labels, raw Todoist filter, and saved filter. It does not explicitly distinguish this tool from close siblings like find-tasks-by-date or find-completed-tasks, so it falls 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 description includes the important constraint that at least one filter must be provided, which is useful usage guidance. However, it does not say when to use this tool versus find-tasks-by-date, find-completed-tasks, or search, so the alternative-selection guidance is implied rather than explicit.

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 as a read-only, idempotent, non-destructive operation. The description adds useful behavioral context beyond them: 'today' includes overdue items, and the default responsibleUserFiltering excludes other users' tasks.

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 short sentences with no filler. The core purpose and the two non-obvious default behaviors are front-loaded and easy to scan.

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 key non-obvious defaults for a date-based task query. Pagination and label-filtering mechanics are left to the fully documented schema and output schema, which is acceptable given their richness.

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 explains all nine parameters. The description reinforces two important parameter behaviors, but adds little unique syntax or meaning beyond the structured 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 states a specific verb and resource: 'Get tasks by date range.' This clearly distinguishes it from generic task-search or mutation siblings, though it does not explicitly name an alternative tool like find-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?

Usage is implied by the date-range focus and the two default-behavior notes, but the description never states when to choose this tool over siblings such as find-tasks or find-completed-tasks. No exclusions or prerequisites 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?

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?

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description adds the important nuance that the write is immediate and irreversible, plus the constraint to confirm the target project with the user. It does not explain merge/conflict behavior (e.g. duplicate task names) for a non-idempotent operation, which would be the remaining high-value detail.

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 tight sentences with no filler: purpose first, sourcing second, precondition and risk last. Every sentence carries information an agent would otherwise have to guess.

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?

An output schema exists so return values need not be described. For a 4-parameter, non-idempotent write tool with full annotation coverage, the description covers purpose, sourcing, prerequisite and risk without leaving an agent unable to call 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?

Schema coverage is 100%, so the schema already documents projectId, locale, templateId and csvFileContent, including the mutual exclusivity. The description's only added value is provenance — that CSV content comes from export-project-template — which is a useful but small increment over 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?

Specific verb+resource with added scope: 'Import a template into an existing project, adding its tasks, sections and comments to whatever is already there.' It also implicitly separates itself from export-project-template, the inverse operation, by describing where the CSV comes from.

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 states the two sourcing paths (template ID/URL vs. CSV from export-project-template) and gives the prerequisite workflow for a new project: 'create the project with add-projects first, then import into it.' It also names when-not to act freely: '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, non-idempotent and open-world, but the description adds meaningfully beyond them: assigning sends a notification to the new assignee, and each task is updated independently so failures are partial and reported per task. Those side-effect and partial-failure semantics are exactly the kind of context an agent needs before firing a destructive batch call.

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?

Four short sentences, zero filler, with the operation/scope front-loaded and the risk mitigations (per-task failure isolation, dryRun) trailing in priority order. Every sentence carries information an agent would otherwise have to infer.

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

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

For a destructive batch mutation with five parameters, the description covers batch limits, partial-failure behavior, notification side effects, and the dryRun escape hatch, and an output schema exists to explain per-task results. Nothing needed to invoke 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% — every parameter, including the operation enum, responsibleUser's "me"/ID/name/email forms, and fromAssigneeUser's optionality, is documented in the schema itself. The description only restates the 50-item cap and mentions dryRun, so it adds essentially nothing new; baseline 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 opens with a specific verb triple (assign/unassign/reassign) plus the resource (tasks) and the batch scope (up to 50 at once), which lets an agent distinguish this from single-object tools like update-tasks or complete-tasks. It stops short of naming a sibling alternative explicitly, so it is clear but not sibling-routed.

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?

"Use dryRun to check the changes first" is a concrete usage recommendation, and the 50-task cap sets a practical boundary. However, there is no explicit when-to-use/when-not guidance and no mention of the obvious alternative (looping update-tasks), leaving the choice largely implied.

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 carry the full safety profile (destructiveHint=true, idempotentHint=true, openWorldHint=false), but the description adds nothing on top. For a destructive cross-context move, it says nothing about what is destroyed or altered — e.g. whether collaborators, folder placement, or visibility are reset — which is exactly the context an agent needs before calling it.

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

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

A single efficient sentence with the core operation front-loaded and no filler. It is arguably too thin rather than too long, but there is zero waste.

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?

An output schema exists, so return values need not be explained, but for a 5-parameter destructive mutation the description omits the side effects of moving a project across contexts. An agent would have to consult the schema and guess at consequences.

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 five parameters including the enums and the conditional workspaceId are documented in the schema. The description adds no syntax or conditional logic beyond that, so the baseline 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 has a specific verb ("Move") and resource ("project") plus the axis of movement (personal <-> workspace), so the operation is unambiguous. It does not differentiate itself from siblings like update-projects or project-management, which could plausibly overlap with this change.

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

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

There is no guidance on when to choose this tool versus update-projects or project-management, and no mention of the required action enum or the conditional workspaceId requirement. The agent must infer all preconditions from the schema.

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 it non-read-only, idempotent, non-destructive, and closed-world. The description adds genuinely non-obvious context beyond that: workspace ordering is a shared default every member sees, reordering a workspace requires permission, and moves are applied before order positions so order is evaluated under the new 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?

Front-loaded lead sentence states the full scope, followed by one sentence per entity type, which is an easy-to-scan structure. It is efficient overall, though the per-type sentences restate schema wording closely, so some content is duplicated rather than additive.

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?

An output schema exists, so return values need no explanation, and the permissions and ordering semantics are covered. It does not address partial-failure or atomicity behavior across the `items` array, which would matter for a batched mutation, leaving a small completeness gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `order` is sibling-relative per entity type, workspace ordering is shared across members, and `parentId` accepts "root" and is personal-projects-only. It is largely a mirror of the schema text, which keeps it out of 5 territory.

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 ("Reorder projects or sections") and immediately disambiguates the three modes it covers: personal projects, workspace projects, and sections. It gives no differentiation from the sibling `project-move` tool, which appears to overlap with the parentId move behavior, so it falls 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?

Usage is implied rather than stated: the reader can infer that `order` reorders within siblings and `parentId` relocates a personal project, and it notes the workspace permission prerequisite. There is no explicit when-not-to-use guidance and no routing to alternatives such as `project-move` or `update-projects`.

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 destructiveHint=true and idempotentHint=false, so the description doesn't need to re-litigate safety. It adds real value by disclosing the preservation semantics — only the date changes, recurrence survives — which the annotations cannot express. It does not cover batch behavior (multiple tasks, partial failure on an invalid id), which keeps it below a 5.

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?

Front-loaded and short, but the recurrence-preservation point is made three times ('preserving recurring schedules', 'keeping recurrence patterns intact', 'without altering their repeat pattern'). Two of those sentences could be merged without losing anything.

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?

An output schema exists, so return values need no explanation, and the single parameter is fully documented. The gap is operational: nothing says what happens if one task id in the array is invalid, which matters for a destructive batch mutation.

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 nested date property already documents the YYYY-MM-DD vs datetime formats and the time-preservation rule. The description adds no parameter semantics beyond that; baseline 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?

Specific verb+resource+scope: 'Reschedule tasks to new dates while preserving recurring schedules,' and it explicitly contrasts with update-tasks. An agent can distinguish it from the sibling without opening either 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?

Gives an explicit when-to-use ('moving recurring tasks to a different date without altering their repeat pattern') and names the wrong alternative (update-tasks) plus the harm it causes (wipes recurrence). Selection is unambiguous.

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?

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description only adds the 'multiple/batch' nuance; it does not disclose permission requirements, whether only the caller's own comments can be edited, or failure behavior when some IDs are invalid.

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 efficient sentence with the verb and scope front-loaded. Nothing is wasted, though there is little structure to speak of.

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

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

For a destructive batch mutation, the description omits the constraints an agent needs: whose comments can be edited, what happens on partial failure, and per-comment error handling. The output schema and annotations help, but the gaps around mutation semantics remain.

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 nested id/content structure is fully documented there. The description's 'multiple existing comments' hints at the array shape and the requirement that comments pre-exist, but adds nothing about the id/content 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?

States a specific verb and resource ('update ... comments') plus batch scope ('multiple existing comments'). It is clear what the tool does, but it does not differentiate itself from siblings like add-comments or delete-object.

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

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

There is no guidance on when to use this versus add-comments (create) or find-comments (read), nor any mention of prerequisites such as needing to be the comment's author.

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 purely functional and adds no unique behavioral traits. The primary behavioral constraints (e.g., destructive nature, mutability) are already defined by the annotations (destructiveHint: true, readOnlyHint: false).

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 tool is described in one extremely concise sentence. Every word serves to define the scope of the operation without superfluous detail.

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

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

Despite the complex input structure (nested array of objects with many attributes), the description remains high-level. While the schema handles the heavy lifting, a slightly more descriptive summary of the update operation's impact would improve completeness.

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

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

Schema coverage is 100%, meaning the description does not need to compensate for missing parameter explanations. Since it provides no additional semantic context beyond the schema, 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 clearly identifies the resource (filters) and the action (update). It is distinct from 'add-filters' and 'find-filters' in the sibling list. It uses a specific action/resource pairing.

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 necessity of existing filters, but provides no explicit advice on whether to first call 'find-filters' or if there are specific conditions (like minimum required fields) for success, making the guidance slightly weak.

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 and idempotentHint=false. The description adds genuinely useful mode-level semantics (shared rename vs. personal full-field update), but it does not warn that shared-label renames propagate to all tasks, nor does it acknowledge that the operation is destructive or non-idempotent. It adds value beyond annotations without fully carrying the behavioral burden.

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 core action and then the mode breakdown. Nearly every clause earns its place, though the parenthetical '(identified by ID)' / '(identified by name)' duplicates the schema's discriminators.

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?

Output schema exists and annotations cover the safety profile, so the description only needs to explain the two update modes, which it does completely and accurately. Missing is any mention of how to discover IDs or that updates apply per-label in a batch, but the essentials for a correct call are present.

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 nested oneOf already documents both branches in detail, including the shared-label rename note. The description restates that branch split at a higher level, which aids quick parsing but adds no syntax or constraint information the schema lacks. 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?

Names a specific verb (update) and resource (labels), and immediately splits the operation into two distinct modes: personal labels by ID and shared labels by name. An agent can tell this apart from add-labels or find-labels from the name and description alone, though the description never names those siblings to reinforce the boundary.

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?

Implies 'use this to modify existing labels rather than create them', but never states preconditions such as needing an existing label ID (from find-labels) or the fact that shared labels must already exist. There is no explicit when-not guidance and no reference to alternatives like add-labels for creation.

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, idempotentHint=false and readOnlyHint=false, so the safety profile is known from structured data; the description adds nothing beyond that. It does not warn that updates overwrite existing field values, that passing description clears it, or that color fallback to charcoal can silently change data — all relevant given the destructive flag.

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 with no waste, but it is under-specified rather than efficient — 'with new values' is vague filler that conveys no actionable information.

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

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

For a destructive, non-idempotent batch mutation with an output schema present, the description should at minimum note that callers must supply the project id and that unspecified fields are left untouched (or not). Return values needn't be explained given the output schema, but the mutation semantics gap is a real omission.

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 nested project fields, enum values, and the 'null/empty string clears description' behavior are already documented in the schema. The description only reinforces the batch/array nature ('multiple existing projects'), which is the baseline expectation when the schema does the heavy lifting.

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

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

States a specific verb (update) plus resource (projects) and clarifies the batch semantics ('multiple existing projects'), which separates it from add-projects and find-projects. It doesn't name any sibling explicitly, but the resource name is distinctive enough within the sibling set.

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 when-to-use guidance, no prerequisites, and no mention of alternatives such as project-management or add-projects for creation. The agent must infer from the name alone that this mutates existing projects rather than creating or reorganizing them.

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 disclose the significant traits: destructiveHint=true, idempotentHint=true, openWorldHint=true, readOnlyHint=false, so the safety burden is largely carried. The description usefully adds patch semantics ("Only include fields that need to change"), which clarifies that omitted fields are preserved rather than cleared. It adds nothing about what happens on an invalid/unknown ID, whether the type discriminator must match the existing reminder's type, or permission requirements.

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 short sentences with no filler, and the core action is front-loaded ahead of the per-item requirement. The final sentence is slightly redundant with the schema's "reminders" property description, but the whole block is compact and easy to scan.

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?

An output schema exists, so return values need not be explained, and the annotations already cover the mutation/destructive profile. What remains missing for a destructive batch mutation (max 25 items) is how to obtain valid reminder IDs, what a failed partial batch does, and whether the type field must match the stored reminder type — meaningful gaps 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% and there is effectively one top-level parameter, so the schema already explains the type/id/field-level semantics in detail. The description restates the type discrimination ("relative", "absolute", "location") which is the one genuinely helpful addition, but adds no format or constraint detail beyond the schema — baseline 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 opens with a specific verb and resource: "Update existing reminders." It names the discriminated type field and the ID requirement, which tells an agent the unit of work is a batch array of identified reminder objects. It does not explicitly distinguish itself from the sibling update_* tools or the create counterpart (create_reminder), but the verb+noun 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?

"Update existing reminders" implies the mutation use case versus create/find_reminders, and "Only include fields that need to change" gives useful partial-update guidance. However, the description states no when-not conditions, no prerequisite that the reminder must already exist and its ID be known, and no pointer to find_reminders for discovering IDs — those conditions are left to 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 already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false and openWorldHint=false, so the safety profile is largely covered. The description adds only the batch scope; it does not explain why the call is flagged destructive (e.g., whether omitting a section in the payload affects it) or that a failed batch may partially apply.

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 with zero filler. It is lean rather than bloated; the only issue is that its brevity leaves gaps the agent must fill from annotations and schema.

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 one parameter, a full schema, an output schema and four annotations hints, most of what an agent needs is present. However, the description omits the prerequisite of resolving section IDs (find-sections) and gives no hint about the destructive/idempotency semantics that the annotations flag but do not explain.

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 each field (id, name, description with null-to-clear) is documented inline, so the baseline of 3 applies. 'With new values' in the description adds nothing the schema does not already state more precisely.

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?

Specific verb+resource ('Update ... sections') plus the batch qualifier 'multiple existing', which tells the agent this operates on already-existing records rather than creating them. It does not explicitly differentiate from siblings like add-sections or find-sections, but the verb and 'existing' constraint make the intent 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 statement of when to use this versus add-sections/find-sections, and no guidance on obtaining section IDs before calling. The word 'existing' weakly implies a lookup prerequisite, but that is inference rather than 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?

The description adds a meaningful behavioral detail: only fields being changed should be sent, which supports safe partial updates. The annotations already declare destructiveHint=true and idempotentHint=false, and the schema documents side effects like label replacement and moving tasks out of sections/parents, so the description does not need to repeat those.

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

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

Two tightly written sentences with no filler. The core purpose is front-loaded, and the partial-update rule is stated immediately after the field categories.

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 input schema, annotations, and an output schema, the description is largely sufficient: it states the operation, the editable categories, and the partial-update expectation. It could be stronger by noting batch size or destructive side effects in prose, but those are covered structurally and do not need repetition.

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 detailed nested field semantics are already provided in the schema, including 'remove,' 'unassign,' and side effects. The description adds only broad categories of updatable fields and the partial-update rule, which is consistent with 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 uses a clear verb-resource pair, 'Update existing tasks,' and lists broad editable areas: content, dates, priorities, and assignments. It implicitly distinguishes updates from creation via 'existing,' but does not explicitly name or contrast with overlapping siblings such as reschedule-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 instruction 'Send only the fields that change' gives useful partial-update guidance, and 'existing tasks' implies this is for modifying already-created tasks. However, it does not explicitly say when to use this instead of sibling tools like reschedule-tasks or complete-tasks, which also affect task state.

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