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

Annotations only state readOnlyHint=false and destructiveHint=false, so the description carries the burden of disclosing side effects. It adds crucial behavioral context: most fields are merged/partially updated, while labelIds is a full replacement list that the caller must enumerate completely. This prevents a common agent failure mode.

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

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

Two tightly packed sentences with no filler. The field list is front-loaded, and the critical labelIds warning is placed immediately after, making the most important caveat easy to notice before calling 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?

For an 8-parameter mutating tool, the description plus a fully documented schema leaves the agent with enough to invoke it correctly: taskId source is in the schema, and the label replacement hazard is explicit. A minor gap is that no return value or post-update behavior is described, but nothing essential for selecting and invoking the tool 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 the baseline is 3 because every parameter is already documented. The description adds cross-cutting semantics beyond the schema—only passed fields change, except labelIds which replaces the entire set. That extra operational guidance justifies one point above baseline.

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

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

The description uses a specific verb ('Update'), identifies the exact resource ('a task'), and enumerates the mutable fields, distinguishing it from sibling tools that update projects, statuses, or labels. The label replacement nuance further removes ambiguity about 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?

The description makes clear that this is the tool for modifying standalone task fields and emphasizes the partial-update behavior. It does not explicitly name alternatives or when-not-to-use conditions, but there is no realistic ambiguity given the tool name and sibling list.

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