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

Even though annotations already mark this as destructive, the description adds critical behavioral detail: tasks are flagged hidden rather than deleted, remain retrievable via list_tasks with show_completed=true and show_hidden=true, and can be restored individually with reopen_task. It also warns that there is no bulk un-clear and explicitly states the return value. This goes well 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?

The description is front-loaded with the main action and scope, then provides dense, relevant detail about hidden state, recovery, destructiveness, and return shape. Every sentence earns its place, and the parenthetical about the Google Tasks UI adds useful real-world context without padding.

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

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

For a single-parameter tool with no output schema, the description is highly complete. It covers what the tool does, what it does not do, side effects, recoverability, destructive nature, and the response format. An agent has everything needed to call it correctly and predict its 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 coverage is 100% and the schema already documents tasklist_id, including the '@default' special value. The description adds that the ID is echoed in the response, but it doesn't need to explain parameter meaning further because the schema handles it fully. 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 specific verb and resource: it clears ALL completed tasks from one list in a single call. It clearly distinguishes itself from deleting tasks, completing individual open tasks, and restoring tasks via reopen_task. The scope and behavior are 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 context: it operates on completed tasks only, leaves open (needsAction) tasks untouched, and has no bulk undo. It also names list_tasks and reopen_task as recovery paths. However, it does not explicitly say when not to use this tool versus a sibling like complete_task or delete_task, so it stops just short of complete routing guidance.

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

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

The annotations already indicate mutation and destructiveness, but the description adds valuable behavioral detail: the operation is reversible, it does not cascade to subtasks, and completed tasks remain listed until cleared with specific flags. It also discloses return behavior. There is no contradiction with annotations because destructiveHint is consistent with mutating task state, and the description clarifies the scope and reversibility.

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 but information-dense. Every sentence contributes either a precise action, a contrast with a sibling, a non-obvious behavioral caveat, or the return contract. It is front-loaded with the core action and then branches into the most decision-relevant caveats.

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 no output schema, the description supplies the return shape ('updated task with status and completed'). It covers reversibility, cascade semantics, listing behavior after completion, and the correct usage boundaries versus siblings. For a two-parameter, fully-schema-documented tool, nothing essential 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 coverage is 100%, so both parameters are already fully documented with provenance and the @default convention. The description does not need to repeat or add parameter detail; it simply relies on the schema, which is acceptable.

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 explicitly that the tool marks a task completed with status=completed and a stamped timestamp. It clearly differentiates itself from reopen_task and delete_task by describing what each sibling does differently. The behavior on parent tasks is also defined, which sharpens the 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?

Gives direct guidance on when to use it ('the right call for done') and when not to ('unlike delete_task', 'does NOT cascade to its subtasks'). It also names reopen_task as the undo path and tells the caller to complete subtasks individually when needed. This is explicit routing information.

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 the annotations (readOnlyHint=false, idempotentHint=false, etc.), the description discloses key behavioral traits: due time-of-day is discarded and never returned, notes are plain text with a max, tasks start as needsAction, hierarchy supports one nesting level, and recurrence is unsupported. No contradiction with annotations is present.

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 dense but every sentence carries operational value. It fronts the core purpose and return fields, then covers date semantics, limits, ordering, state, and a limitation—all in about 80 words with no filler or repetition.

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

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

For a 6-parameter tool with no output schema, the description is remarkably complete: it lists return fields, explains ordering and nesting, sets expectations about state (needsAction), and flags the recurrence limitation. An agent can select and invoke this tool correctly without needing 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?

Even though schema coverage is 100%, the description adds meaning beyond the JSON schema: it explains how 'due' time is stripped, that parent creates a subtask with 'one level of nesting reliably', that omitting both parent and previous lands the task at the top, and that previous is a sibling insert-after. These semantics are not 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 uses a specific verb and resource ('Creates a task in a list') and explicitly enumerates the return payload ('id, title, position, webViewLink, ...'). It also distinguishes itself from siblings like create_tasklist and update_task by focusing on task creation and returning the created 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?

The description provides explicit when-not guidance: 'Recurrence cannot be created or read through the API' and 'New tasks start as needsAction — use complete_task to complete.' This routes the agent to an alternative tool under a clear condition, which is exactly what this dimension rewards.

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 valuable behavioral context beyond the annotations: the created list is returned, the API accepts only a title, the returned id is central to later task operations, and Google caps lists per account with quota failures surfacing as HTTP errors rather than silent failures. 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?

Every sentence earns its place: return shape, scope of accepted settings, downstream importance of the id, and quota/error behavior. The description is compact, front-loaded, and free of filler.

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

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

For a single-parameter creation tool with no output schema, the description is complete: it states what happens, what is returned, how the result is used, and what error behavior to expect. The low complexity means no significant gaps 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 coverage is 100% and the title parameter is already well documented in the input schema. The description adds context by emphasizing that title is the only accepted setting, which reinforces the schema but does not fundamentally enrich the parameter semantics.

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: 'Creates a new task list and returns it.' It also names the returned fields, distinguishing this creation tool from the many sibling get/update/delete/list tools in the same family.

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 context is clear: this is the tool for creating a list, and the description explains that the returned id becomes the tasklist_id required by task tools. It does not explicitly compare itself to alternatives like update_tasklist, but its role is unambiguous from the description and sibling set.

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

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

Annotations already signal destructive, but the description adds crucial behavioral detail: permanent deletion, soft-delete visibility window with show_deleted=true, cascading to subtasks, and the response shape. This goes well beyond what the annotations convey.

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 dense but every sentence adds a distinct fact: permanence, distinction from completion, soft-delete behavior, cascading, and return value. It is front-loaded with the most decision-relevant 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?

Covers the destructive semantics, the alternative tool, the observable side effects, and the return value. With a destructive operation and no output schema, this description gives an agent 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?

The input schema has 100% description coverage, so both parameters are already self-documenting. The description adds no param-specific meaning, but the schema carries the full burden; 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?

States the exact operation ('Deletes a task permanently') and immediately distinguishes itself from complete_task, so an agent can tell the two apart. The resource and effect are 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?

Explicitly says when NOT to use it ('this is NOT the same as completing it') and names the correct alternative ('use complete_task instead'). Also discloses cascading deletion of subtasks, giving clear selection 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?

Goes beyond the destructiveHint annotation by adding crucial behavioral context: no undo, no trash, deletion of every task in the list, rejection of the default list, and the exact return shape. This gives the agent a full picture of the irreversible side effects.

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?

Every sentence earns its place: the action, the irreversibility, the default-list limitation, the alternatives, and the return value are all included without verbosity. The most critical information is front-loaded.

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 single-parameter tool, this description is complete. It covers side effects, edge cases, alternatives, and return value, and the annotations already convey the safety profile. Nothing essential 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 input schema already documents tasklist_id, including the '@default' alias. The tool description itself does not add parameter-level detail, but it also does not need to because the schema fully covers 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?

States the specific verb and resource: 'Deletes a task list AND every task in it, permanently.' It clearly distinguishes itself from delete_task and clear_completed_tasks by emphasizing the cascade deletion, so an agent knows exactly what this 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?

Explicitly explains when to use this tool versus alternatives: if you only need to empty the list but keep it, use clear_completed_tasks or delete tasks one by one. It also warns that the default task list cannot be deleted because the API rejects it.

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, open-world, and non-destructive behavior. The description adds valuable behavioral context beyond that: it is the safe verification path after ambiguous writes and writes are never retried automatically.

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: the first front-loads the core action and returned data, and the second adds a high-value usage caveat. There is 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 simple two-parameter read operation, the description is complete: it lists the returned fields, conveys the safe read-only nature, and explains a key use case. The absence of an output schema is compensated by the explicit field list.

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 task_id and tasklist_id thoroughly. The description only refers generally to 'by id' and does not add meaning beyond the parameter definitions, which matches the baseline for full 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 states a specific verb ('Fetches'), a specific resource ('one task by id'), and enumerates the returned fields. It clearly distinguishes get_task from list_tasks (which fetches many tasks) and get_tasklist (which fetches a task 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?

The description gives a concrete when-to-use case: verifying state after an ambiguous write failure. It does not explicitly name alternatives such as list_tasks, but the 'one task by id' scope makes the selection context clear enough.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond those hints: the returned resource is metadata-only, '@default' can resolve the real id, and actual tasks are not included.

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 carrying distinct information: what is fetched, the '@default' special value, and the key limitation that tasks are elsewhere. The most important identifying information is front-loaded.

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 one-parameter, read-only, idempotent fetch with no output schema, this description is complete. It states the resource identity, the parameter's special value, the returned fields, and the boundary between task lists and tasks. 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 coverage is 100% and the parameter description already documents tasklist_id, including the '@default' behavior. The description reinforces this and adds the purpose 'useful to resolve its real id', but it does not substantially extend the schema's meaning. 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 ('Fetches'), names the exact resource ('one task list by id'), and lists the returned fields. It clearly distinguishes itself from list_tasklists (list all) and list_tasks (fetch tasks) by scoping what this tool does not return.

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 for when this tool is appropriate: fetching a single task list, including via '@default'. It also explicitly directs task retrieval to list_tasks, and the singular-by-id wording implicitly distinguishes it from list_tasklists. It does not explicitly exclude list_tasklists, but the distinction is clear enough.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive; the description adds concrete behavioral details beyond that: returned fields, RFC3339 format, page_size cap/default at 1000, page_token chaining, and the absence of search or ordering. It even states 'one call usually returns everything,' which helps the agent decide whether to paginate.

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 dense sentences with no filler. The key result fields and entry-point role are front-loaded, followed by pagination details and API limitations. 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?

For a read-only list call with two optional, fully documented parameters and no output schema, the description covers return fields, pagination, default-list alias, and API limitations. An agent has enough information to invoke the tool and interpret the result 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 adds operational context not in the schema: page_token comes from nextPageToken, page_size caps at 1000, the API default is already 1000, and one call usually returns everything. This is useful but not a dramatic expansion 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 explicitly states the verb and resource: 'Lists the user's task lists: id, title, updated (RFC3339)'. It also frames the tool as the entry point for task tools, distinguishing it from task-specific siblings like list_tasks and get_tasklist.

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

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

It gives explicit when-to-use guidance: 'task tools need a tasklist_id from here' and mentions the '@default' alias. It also states when-not-to-expect more: 'The API has no search or ordering — filter client-side,' and explains pagination defaults so the agent knows one call usually suffices.

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

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

Annotations already mark this as read-only and idempotent, and the description adds substantial non-obvious behavior: the API never stores a time of day for due dates, tasks completed in Google's UI are flagged hidden, there are no push notifications, and due bounds don't match tasks without a due date. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and output fields, and every sentence carries useful information. However, it is quite dense and could benefit from structured bullets; it is appropriately sized for the complexity but not maximally concise.

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 enumerates all returned fields and covers pagination, sync patterns, filter semantics, and API quirks. For a 12-parameter list/filter/sync tool, this is remarkably 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%, so the baseline is 3, but the description adds important meaning beyond the schema: the interplay of show_completed and show_hidden for reliable completion sync, the opaque nature of position and the move_task constraint, and that tasks lacking a due date never match due bounds.

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 ('Lists'), a clear resource ('tasks in one list'), and enumerates the returned fields (id, title, notes, status, due, completed timestamp, etc.). It is easy to distinguish from siblings like get_task (single task) and list_tasklists (task 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?

The description gives strong context for when to use filters and pagination: incremental sync with updated_min and show_deleted/show_hidden, page_token for pagination, and the meaning of due_min/due_max vs completed_min/completed_max. It does not explicitly name alternative tools, so when-to-use vs alternatives is not fully 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?

While annotations declare readOnlyHint=false and idempotentHint=false, the description adds substantial behavior beyond them: the default semantics of omitting parent (top level) and previous (first among siblings), the combined-omission consequence (very top of list), and the fact that positions are opaque API-maintained strings. It also discloses the cross-parameter constraints and the return value ('Returns the task with its new position'). None of this is in 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 dense but every sentence earns its place: core action, omission defaults with a consequence clause, exclusivity rationale, constraints, and return value. It is front-loaded with the purpose in the first sentence and contains no repetition of schema content 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?

The tool has no output schema, so the return-value statement is essential and present. Given the complexity of three orthogonal movement modes, default behaviors, and three constraints, the description covers everything an agent needs to invoke it correctly: purpose, parameter interaction semantics, constraints, and result. No meaningful gap remains.

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 solid per-parameter docs, so the baseline is 3 and the schema already carries the heavy lifting. The description adds interaction-level meaning the schema cannot: how omitting parent and previous combine to place the task at the very top, and the constraint that parent and previous must reside in the destination list. This elevates it above baseline, though it complements rather than rescues 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 'Moves a task' and precisely enumerates the three movement dimensions (under a parent, after a sibling, into another list), which is a specific verb+resource statement that distinguishes it from every sibling. Crucially, it explains why update_task cannot achieve this ('parent/position are read-only fields'), making the differentiation from the closest sibling explicit.

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 'This is the ONLY way to change hierarchy or order,' an explicit when-to-use directive backed by the read-only-fields rationale. It also gives when-not conditions: parent/previous must belong to the destination list and assigned/recurrent tasks cannot be moved between lists. The alternative route (update_task) is implicitly excluded by the read-only fields explanation, which is sufficient 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 signal destructive and open-world behavior, but the description adds crucial context: the Bearer token is added automatically, method defaults to GET, and PATCH/PUT/POST/DELETE hit live data with no confirmation. This goes well beyond the structured annotations and warns the agent about irreversible actions.

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 with no filler. The purpose is front-loaded, followed by a concrete example, and ends with the most important safety warning. 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 an arbitrary raw API call tool with no output schema, the description provides all necessary context: base URL, path handling, query string support, authentication, method default, safety warning, and guidance on when to prefer typed tools. 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%, so the baseline is 3. The description reinforces the path-relative-to-base, method-default, and body-handling semantics, but these are already fully documented in the input schema. The escape-hatch examples add color but not new parameter-level meaning.

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 precise purpose: an escape hatch to call any Google Tasks API v1 path directly. It explicitly differentiates from the typed sibling tools by saying it exists for requests the typed tools don't cover, with concrete examples like full-resource PUT and unsupported query combinations.

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 says exactly when to use it ('for requests the typed tools don't cover') and when not to ('prefer the typed tools when one fits'). This gives an agent clear decision criteria for selecting this tool over its 14 siblings.

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 the annotations, the description discloses the exact state change (needsAction, cleared timestamp), hidden-task behavior, deletion permanence, and that the updated task is returned. These details meaningfully exceed annotation coverage, and there is no contradiction with destructiveHint or idempotentHint.

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 each add distinct value: the core behavior, the hidden-task edge case, and the deletion limitation. The most important action is front-loaded, with no filler or repetition.

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

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

With only two fully documented parameters and no output schema, the description covers the key behavioral details an agent needs: what changes, what edge cases exist, what the tool cannot do, and what it returns. Annotations cover the safety profile. Nothing essential 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?

The input schema already documents both parameters fully, including where to get them, so the description does not need to repeat parameter details. It adds no extra parameter-level semantics beyond the schema, so the baseline score 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 states a specific action with a clear verb and resource: 'Reverts a completed task to needsAction and clears its completed timestamp.' It also explicitly calls itself 'the undo for complete_task', making its relationship to sibling tools 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?

It names the inverse tool, complete_task, and the related clear_completed_tasks flow. It also provides a when-not case: 'Cannot resurrect a deleted task — deletion is permanent.' This is explicit guidance on when to use the tool and what its limits are.

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?

Goes well beyond the annotations by explaining PATCH partial-update behavior, the clear_due/clear_notes semantics, and the important Google API quirk that empty strings do not clear fields. It also discloses that parent and position are read-only in this resource. This adds substantial behavioral context beyond readOnlyHint/idempotentHint/destructiveHint.

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 tight sentences: core behavior, clearing rules, and explicit exclusions plus return value. Every sentence earns its place and the most important information is front-loaded.

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 100% schema coverage and no output schema, the description provides enough contextual glue: required IDs come from list/create tools, optional fields are documented, clearing behavior is explained, and the return value is stated as the updated task. An agent has everything needed to select and call this 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 100% of parameters, so the baseline is 3, but the description adds operation-level meaning that the schema alone does not: only provided fields change, at least one is required, and clear flags erase rather than replace. It also notes that empty strings will not clear fields, which is essential for correct use.

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 ('Changes') and resource ('a task's title, notes and/or due date') and distinguishes itself from siblings by explicitly excluding completion changes and move/re-parent operations. This lets an agent differentiate update_task from complete_task, reopen_task, and move_task without opening schemas.

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 explicit when-not-to-use guidance: completion status changes belong to complete_task/reopen_task, and re-parenting/reordering belongs to move_task. It also clarifies PATCH semantics and the requirement that at least one field be provided, so the agent knows when this tool is appropriate.

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

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

Annotations already signal mutation and idempotency, so the description creditably adds the PATCH method, the exact scope of change, and the return behavior. The destructiveHint is not contradicted because renaming overwrites the previous title; the description merely clarifies that tasks are unaffected.

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 cover the action, HTTP method, scope limitation, side-effect guarantees, and return value with no filler. The most important information is front-loaded.

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 rename operation with rich schema descriptions and annotations, the description covers the operation, its non-effects, and the response. Nothing essential for an agent 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%, so the schema already documents both tasklist_id and title in detail. The description does not add parameter-specific semantics beyond reinforcing that title is the only changeable field, which is a neutral contribution.

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 the specific verb 'Renames' and a clear resource, 'a task list,' and reinforces scope by noting the API only allows changing the title. It distinguishes itself from sibling task-related tools by stating that tasks, order, and completion state are untouched.

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 states that the tool's only effect is renaming the list and that task content, order, and completion state are not altered, which gives a strong sense of when to use it. It does not explicitly name alternatives like update_task, but the exclusion of task-level changes provides practical routing guidance.

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