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

The description directly contradicts the destructiveHint=true annotation by claiming tasks are only 'hidden' and 'remain retrievable.' This is a serious inconsistency flagged as an annotation contradiction. The description should have disclosed the destructive nature or aligned with the annotation.

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 the primary action front-loaded and a concise explanation of the retention behavior. No redundancy or wasted words.

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

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

This is a simple one-parameter tool, but the description provides misleading information about destructiveness. Given the annotation set and lack of output schema, the description fails to convey the true impact of the operation, making it incomplete.

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

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

The input schema already has 100% coverage with a clear description for list_id. The tool description adds no additional meaning 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 ('hide') and resource ('every completed task in a list'), clearly distinguishing it from siblings like delete_task or complete_tasks. It also explains the observable effect (removal from Google Tasks UI) which further clarifies the tool's scope.

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

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

The description clarifies when to use the tool by describing its non-destructive behavior and the fact that tasks remain retrievable via include="all". However, it does not explicitly name alternative tools or state when not to use it, relying on implicit contrast with delete_task.

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 idempotentHint=true and destructiveHint=false, and the description's 'Safe to repeat' simply reiterates this. No new behavioral context is added beyond what annotations provide, such as return behavior or side effects. With annotations covering the safety profile, this is acceptable but not exemplary.

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

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

The description is three sentences, each earning its place: the first states the action, the second provides usage guidance, and the third reassures idempotency. It is front-loaded and concise with no 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 write tool with two parameters and no output schema, the description covers the purpose, the preferred usage over a sibling, and the safety of repetition. Combined with the annotations (idempotent, non-destructive), the agent has sufficient context 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?

The input schema has 100% coverage with descriptions for both 'list_id' and 'task_ids'. The description adds no extra parameter-specific details beyond the schema. Since the schema already documents the parameters, a 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 the specific verb 'Mark' with the resource 'tasks done', clearly stating the tool's function. It also distinguishes from the sibling 'update_task' by explicitly saying 'prefer it over update_task for finishing things', making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use the tool: 'This is the most common write by a wide margin — prefer it over update_task for finishing things.' It also notes 'Safe to repeat', reinforcing the idempotency for safe re-invocation. This gives clear direction on choosing this tool over alternatives.

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

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

The description adds context beyond the annotations by explaining that due is calendar-date only and that relative dates must be resolved manually, plus the default-list behavior. These details align with the annotations (readOnlyHint=false, destructiveHint=false) and do not contradict them.

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 concise sentences, front-loaded with 'Add a task.' Every sentence earns its place: default list, date handling, and structural parameters. No fluff 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 create operation with no output schema, the description covers purpose and key parameter nuances, providing enough to use the tool correctly. It doesn't mention the return value, but that is not critical for creation. A minor gap is the lack of explicit guidance on when to use this vs. create_tasks.

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 baseline is 3. The description adds value with the default list_id behavior and the instruction to resolve relative dates, but mostly reiterates schema descriptions for due, parent_id, and previous_id.

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 clear, specific verb and resource: 'Add a task.' It distinguishes itself from siblings like create_tasks (plural, bulk) and update_task by emphasizing singular creation and unique parameter behaviors (parent_id for subtasks, previous_id for ordering).

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 practical usage guidance: omit list_id to use the default list, resolve relative dates before calling, and use parent_id/previous_id for structure. It doesn't explicitly name alternatives or exclusions, but the context is clear and actionable.

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 destructiveHint=false, so the write nature is known. However, the description adds no additional behavioral context, such as whether the created list is returned, whether duplicate titles are allowed, or any side effects; it merely restates the title.

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

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

The description is a single sentence, clear and front-loaded, with no wasted words. However, it is so minimal that it borders on under-specification.

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 one-parameter creation tool with no output schema, the description is minimally adequate. Still, it leaves open questions about the return value and list semantics, so it is not fully complete.

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

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

The input schema covers 100% of parameters, with a clear description for 'title'. The description adds no extra parameter semantics, but this is acceptable given the 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 the specific verb 'Create' and resource 'task list', clearly distinguishing it from task-level tools like create_task or create_tasks. However, it is terse and does not explicitly differentiate between creating a list vs. creating tasks within a list.

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 tool versus alternatives such as create_task, create_tasks, or when to avoid it. The sibling tools exist but the description provides no context for selection.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds the batch behavior and per-entry list targeting, but does not disclose partial-failure semantics, atomicity, or return behavior. Given the annotations present, this is acceptable but not rich.

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

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

Two concise sentences that are front-loaded with the core action, immediately followed by usage guidance and a useful nuance. 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?

The description covers purpose, usage, and one behavioral nuance, but for a batch mutation tool it omits important operational details such as atomicity, partial-failure handling, and whether created tasks are returned. Given no output schema, some of this context would be valuable for the agent.

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 parameters are fully documented. The description adds meaningful semantic value by clarifying that each array entry can target a distinct list, which informs the use of the optional 'list_id' field beyond what the schema states.

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 the specific verb 'Add' with the resource 'several tasks at once', clearly distinguishing this batch operation from the sibling 'create_task'. It also names the exact scenario ('when the user lists multiple things') and notes that entries may target different lists.

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 guidance: 'Use this instead of repeated create_task calls when the user lists multiple things.' This tells the agent when to use this tool and which alternative to avoid, effectively covering both the when and the when-not.

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 and idempotentHint, but the description adds crucial specifics: permanence ('cannot be undone'), refusal behavior for repeating tasks, and the risk of deleting the whole series. This goes beyond annotation-covered ground.

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 tightly written sentences with no fluff. Front-loaded with the destructive nature, then key caveat, then alternative. 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 tool's simplicity and coverage by annotations/schema, the description addresses the main decision points: permanence, repeating-task hazard, and alternative for finished work. Minor gap: no mention of return value, but for a delete tool this is often non-critical and output schema is absent.

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 covers all parameter descriptions, but the description adds semantic value for force by explaining why it exists (avoid deleting entire repeating series). This context is not in the schema and helps the agent decide when to set force=true.

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

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

The description uses a specific verb-resource pair ('permanently delete a task') and explicitly distinguishes from siblings by recommending complete_tasks for finished work. This makes the tool's purpose unmistakable.

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 clear when-to-use guidance and explicit exclusion: 'Prefer complete_tasks for finished work.' Also explains the conditional use of force for repeating tasks, which is a critical usage nuance.

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 and readOnlyHint false, but the description adds valuable context: it deletes all tasks in the list, is permanent, and requires confirm=true. This goes beyond the safety flags and explains the operational impact, making behavior clear.

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 primary action and consequence, and zero redundancy. Every phrase earns its place: the destructive scope, irreversibility, and required guard.

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 simplicity of the tool (2 required params, no output schema, no nested objects) and strong annotations (destructiveHint, readOnlyHint), the description covers all essential behavioral information: what gets deleted, permanence, and the confirm requirement. Nothing critical 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% for both parameters, so the description's mention of 'confirm=true' adds little beyond what the schema already states. It does not introduce new parameter semantics or clarify usage 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+resource ('Permanently delete a task list') and clarifies the scope ('and every task in it'), distinguishing it from sibling tools like delete_task and clear_completed. It also conveys the permanence and the required confirm flag, leaving no ambiguity about its function.

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 context is implied: this is for permanent deletion of a list and its tasks, and the description notes it cannot be undone. However, it does not explicitly say when to use this versus alternatives like delete_task or clear_completed, nor does it mention any exclusions or prerequisites beyond confirm=true.

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, so the safe read nature is known. The description adds that the result includes notes, links, and subtask parent, which is useful output context, but it does not disclose potential errors, permissions, or other behavioral traits beyond what annotations provide. The addition is modest, aligning with a 3.

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

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

The description is a single sentence of 10 words, front-loaded with the core action ('Full detail for one task') and efficient in listing examples. 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?

Despite having no output schema, the description gives a reasonable sense of the return by mentioning 'full detail' and listing specific fields (notes, links, subtask parent). It does not discuss error handling or alternative tools, but for a simple read operation with good annotations, it is adequately 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 coverage is 100%, with both list_id and task_id described (e.g., 'List id, title, or alias' and 'Task id, as shown in square brackets'). The description adds no parameter-specific detail 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?

The description clearly states 'Full detail for one task' which identifies a read operation for a single task, distinguishing it from list_tasks (many) and search_tasks. It also enumerates specific contents (notes, links, subtask parent) that reinforce its 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 description implies usage for when a single task's full details are needed, but it does not explicitly compare against siblings like list_tasks or search_tasks, nor does it provide exclusions. The 'one task' phrasing is a subtle guideline, but more explicit direction would improve the score.

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, so the read-only nature is known. The description adds useful context about the return format (a short alias and the real id), which goes beyond the annotation to explain what the tool provides. No contradictions.

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 only two sentences, front-loaded with the core action, and every phrase adds value: what is shown, the output format, and how to use the result. 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?

For a simple read-only tool with no parameters and good annotations, the description is complete. It covers the action, the output fields (alias and id), and the relationship to other tools via list_id. No missing critical information.

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

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

The input schema has zero parameters, so the baseline is 4. The description does not need to explain parameter syntax, but it does clarify the output (alias and id) which is semantically relevant for downstream use of the list_id.

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 ('Show') and resource ('every Google Tasks list on the account'), and clearly differentiates from siblings like list_tasks by focusing on task lists rather than tasks. It also states the output includes a short alias and real id.

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

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

The description states 'Either can be passed as list_id to the other tools,' clearly indicating this tool is a prerequisite for other task tools that require a list_id. It does not explicitly exclude alternatives, but the context makes it obvious when this tool is needed.

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, so the safe-read behavior is covered. The description adds valuable constraints: due dates are calendar dates only, and the Google Tasks API cannot store/return a due time. It also clarifies that omitting list_id spans all lists. This goes beyond the annotations without contradicting them.

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 followed by essential scoping details. Every word earns its place; the second sentence about due-date limitations is concise yet important.

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 5 optional parameters, full schema coverage, and no output schema, the description provides a sufficient overview. It explains the list-wide vs. single-list behavior and the date-range option, leaving parameter details to the schema. Minor gap: no mention of sorting or pagination, but these are not critical for a simple read-only list operation.

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

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

Schema description coverage is 100%, so each parameter is already documented. The description does not add new parameter-specific semantics beyond what the schema provides (e.g., due_after due_before YYYY-MM-DD format is already in the schema). The mention of the API's date limitation is a behavioral note, not a parameter semantics enhancement.

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 'List tasks' with concrete scoping options ('from one list and/or within a due-date range'), and distinguishes itself from siblings like get_task (single task) and list_task_lists by clarifying it can cover every list when list_id is omitted. The verb+resource+scope is specific and unambiguous.

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

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

The description gives clear usage context: 'Omit list_id to cover every list' and combined list/date-range filters imply when to use this tool. It does not explicitly name alternatives (e.g., search_tasks), but the filtering semantics are adequately conveyed for most 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 it as non-read-only, non-destructive, idempotent, and open-world. The description adds one useful behavioral edge case: 'repeating tasks cannot be moved between lists.' However, it does not disclose other potential side effects (e.g., interaction of parent_id and previous_id, or preservation of subtasks when moving lists), so the added value is modest.

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 wasted words. The first sentence front-loads the core capabilities, and the second adds a crucial limitation. Every element contributes directly to understanding the tool.

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 five parameters, full schema coverage, and no output schema, the description covers the key capabilities and one limitation. It is mostly complete, but could benefit from clarifying how operations combine (e.g., reordering while moving lists) or what happens to subtasks when moving lists. The provided annotations and schema fill many gaps, so the description is adequate.

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 is 3. The description adds meaning by mapping operations to parameters: 'Reorder' cues previous_id, 'make it a subtask' cues parent_id, and 'move it to another list' cues destination_list_id. This helps differentiate the purpose of destination_list_id from the required list_id.

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 multiple specific operations: 'Reorder a task, make it a subtask, or move it to another list.' Each verb references the task resource and unique scopes (position, parent, list), which distinguishes it from sibling tools like update_task or complete_tasks.

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

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

The description implies when to use the tool (when you need to reorder, change parentage, or move lists) but does not explicitly name alternatives or state when not to use it. The only explicit exclusion is the repeating-tasks constraint, which is a limitation rather than a usage guideline.

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

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

The description goes beyond the readOnlyHint and openWorldHint annotations by disclosing key behaviors: case-insensitive substring matching, client-side filtering due to lack of API search endpoint, and the note that completed tasks may be hidden unless 'completed' or 'all' is used. This adds substantial behavioral context.

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

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

The description is two sentences: the first states purpose and scope, the second explains the technical mechanism and intended use. It is front-loaded, concise, and 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?

Given the tool's simplicity, 100% schema coverage, and provided annotations, the description is complete. It explains what the tool does, how it works, and when to use it. The absence of an output schema is acceptable because return format is not critical for a search tool and the description adequately implies results.

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% — both 'query' and 'include' have clear descriptions. The tool description does not add meaning beyond the schema for these parameters; it mostly reiterates the query scope. Therefore, 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 clearly states the tool's function: 'Find tasks whose title or notes contain the query, across every list.' It uses a specific verb ('Find'), identifies the resource ('tasks'), and specifies scope ('across every list'), effectively distinguishing it from sibling tools that operate on single lists or 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?

Provides explicit usage context with 'Use it to locate a task before acting on it.' It also explains the client-side filtering rationale, which implies when it is appropriate. However, it does not explicitly name alternative tools or give when-not-to-use guidance, so it stops short of 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 cover idempotency (idempotentHint: true), non-read-only nature, and non-destructive nature. The description only adds 'Safe to repeat', which is redundant with idempotentHint. No additional context about side effects, permissions, or error cases is provided.

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?

Single sentence, 11 words. It is efficiently front-loaded and contains no 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 two-parameter mutation tool with strong annotations and full schema coverage, the description is adequate. It could benefit from naming the inverse relationship to complete_tasks, but it's not necessary for basic usage.

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

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

The input schema provides full descriptions for both parameters (100% coverage), so the description does not need to elaborate. It adds no extra semantic meaning beyond 'one or more' matching the task_ids array.

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 ('Mark... as not done again') and clearly identifies the resource (completed tasks) and scope (one or more). It distinguishes from sibling 'complete_tasks' by describing the inverse 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 description implies usage for reopening completed tasks but does not explicitly state when to use this tool versus alternatives like 'update_task' or 'complete_tasks'. No exclusion criteria 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?

Adds meaningful behavioral context beyond annotations: patch behavior (only passed fields touched, omitting notes leaves existing notes intact), and clear_due semantics. This complements the annotations (readOnlyHint=false, destructiveHint=false) without contradiction, and gives the agent essential knowledge for safe invocation.

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

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

Three sentences, each earning its place: the first states the core function, the second clarifies patch behavior and clear_due, and the third provides a critical limitation with an alternative. No fluff 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 straightforward update tool with 6 parameters and no output schema, the description covers all essential aspects: the fields that can be changed, the guardrails for partial updates, how to clear a due date, and what cannot be done. It is sufficiently complete for an agent to invoke 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?

Description adds value beyond the schema by explaining patch semantics that apply to all parameters, and specifically clarifies due/clear_due behavior and notes omission. This compensates for the schema's lack of descriptions on notes and title, and enhances the 67% 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 specific verb 'Change' with the resource 'task' and enumerates the fields (title, notes, due date). It also distinguishes itself from the sibling tool move_task by explicitly stating it cannot change parent or position.

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-not guidance ('Cannot change parent or position') and names the alternative ('use move_task for that'). It also clarifies patch semantics, telling the user that only passed fields are touched, which indicates when to use the tool (when modifying specific fields) and how to omit fields safely.

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