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

No annotations are provided, so the description must carry the behavioral burden. It discloses that this is a partial update ('Pass only the fields to change') and sets a soft safety rule on assignment and priority. It also clarifies the relationship between description and documentId. While it doesn't state explicitly that changes are irreversible or highlight side effects, the partial-update framing and priority/assignment cautions give adequate transparency for a mutation tool.

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 entire description is one focused paragraph with no filler. The first sentence states the core action, and each subsequent sentence adds a specific, necessary rule (partial update, description vs document, assignment scope, blocked reason, priority). It is front-loaded with the most important information and 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 a tool with 12 parameters, low schema coverage, and no output schema, the description covers the critical behaviors: partial updates, the summary-vs-document pattern, assignment constraints, blocked status requirements, and priority handling. It doesn't mention return values, but as an update tool that is less critical. The main omissions are details on fields like title/size/type, but those are self-evident. Overall it provides sufficient context for an agent to call 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?

Schema coverage is only 42%, so the description must compensate. It does: it explains that description is for summaries, that documentId links a spec document, that blockedReason is only for blocked status, and that priority should not be invented. It also implies that status supports 'done' and epic moves. It doesn't add context for every parameter (e.g., size, type, title), but it covers the ones that carry ambiguity, making the field meanings more concrete than the schema alone.

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 'Update a task,' a clear verb+resource, then immediately gives concrete use cases: 'mark a task done (status: 'done') or move it between epics.' It also specifies behavioral rules like not inventing priority. This strongly distinguishes it from creation/list tools and tells an agent exactly what the tool is for.

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 explains when to use the tool: to mark done, move epics, and set status. It also gives negative guidance: 'Work only on items assigned to the user unless told otherwise; see list_tasks assignee='me'' and 'Don't invent priority.' It also advises creating a document for detailed specs instead of long descriptions. It doesn't explicitly name sibling tools like update_task_comment, but it does give clear context for when this update tool is appropriate.

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