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

Beyond the annotations (idempotentHint=true, destructiveHint=false), the description reveals partial-update semantics ('Only fields you pass are changed; omitted fields stay as-is'), the one-way nature of requiresReview, and the atomic all-or-nothing refusal when sending false against a standing flag. These are non-obvious behavioral traits that materially affect how the tool should be called.

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 purpose is front-loaded in the first sentence and the requiresReview exception is a necessary warning, but the one-word 'Idempotent.' sentence duplicates the idempotentHint annotation, and the final sentence is dense. Overall it is compact and well-ordered, earning a 4 rather than a 5.

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 11 parameter schema carries detailed descriptions for project, assignee, blockedBy, verification, and requiresReview, the tool-level description can stay short and still be sufficient. It explains the patch model and the one dangerous flag, and directs the agent to complete_task for releasing flagged work. The absence of any return-value note is a small gap, but no output schema exists and the description covers the non-obvious call semantics.

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 connects user intents to parameters (rename→title, re-prioritize→priority, re-estimate→estimateMinutes) and adds the crucial patch semantics that omitted fields are untouched. With only 36% schema description coverage, this helps, but it doesn't individually explain the many undocumented fields such as dueAt, description, or estimateMinutes, leaving the schema types to carry that weight.

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 'Use this when the user wants to rename, re-prioritize, re-estimate, or otherwise edit an existing task,' giving a specific verb, resource, and example fields. It clearly separates update from create_task via 'existing task,' but it does not explicitly rule out overlapping siblings like move_task or complete_task, so differentiation is implicit rather than named.

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...' is an explicit trigger condition, and the requiresReview paragraph states the one case where update_task must not be used to clear the flag, naming complete_task as the alternative. This provides clear when-to-use and when-not-to-use guidance for the trickiest scenario, though it doesn't enumerate alternatives for every sibling.

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