update_task

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

Goes well beyond the annotation hints: it discloses that links/addLinks both MERGE and cannot destroy by omission, that re-sending a pair is a no-op, the exact application order (clearLinks -> links+addLinks -> removeLinks), that clearLinks is the only wholesale-destructive path, and the refusal modes (links: [] refused, TASK_NOT_FOUND changes nothing, verifyReason alone refused as E_USAGE). None of that is derivable from readOnlyHint/destructiveHint/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?

Purpose is front-loaded, a dryRun-style LINKS block separates the dense link rules, and every sentence about merge/surgical/clear semantics earns its place. The final sentence describing CLI flag parity (--set-parent/--relates/etc.) is length the MCP caller cannot act on and is the one trimmable element.

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 14-param mutation with no output schema and only one required field, the risky link and verification paths are documented thoroughly enough to call correctly. The omissions are dryRun (does it validate or no-op?) and commitMessage, plus no statement of what the tool returns after a successful update.

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?

With only 50% schema description coverage across 14 params, the description carries real weight: it fully explains links, addLinks, removeLinks, clearLinks, setVerify, and verifyReason, including the ordering contract and empty-array refusal. It leaves branch, dryRun, and commitMessage entirely undefined in both schema and description, which is the remaining gap.

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?

"Update an existing task" states a specific verb and resource, and the follow-up enumerates the updatable surfaces (status, title/description, comments, links). It stops short of naming the siblings it overlaps with — add_comment and verify_task — so an agent must infer that the `comment` and `setVerify` params here are alternatives to those 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?

Strong condition-based guidance for each mode: merge vs surgical remove vs wholesale clear, and the three setVerify verdicts with the requirement that "cannot" needs verifyReason and that "pass" is required for annotated tasks at the review transition. It does not route among sibling tools (e.g. when to call add_comment or verify_task instead), so it is clear context without explicit alternatives.

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