update_task

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is partly carried by structured fields. The description adds one behavioral detail (null clears notes or due), which is useful, but does not mention destructive effects, required permissions, or partial-update semantics beyond what the annotations imply.

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 short sentences, zero waste, front-loaded with the action and the affected fields. 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?

With no output schema and half the parameters undocumented in the schema, the description should do more to cover update semantics, status enum behavior, and when to prefer dedicated tools like complete_task or reopen_task. It is adequate but leaves clear gaps for a mutation tool with sibling overlap.

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 50%, with due and the two ID fields documented in the schema but title, notes, and status lacking descriptions. The description adds meaning by stating which fields can be patched and that null clears notes/due, which compensates somewhat for the uncovered parameters, but it does not clarify status values or title constraints.

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 (Patch) and resource (task) and enumerates the mutable fields (title, notes, due date, status). It is clear what the tool does, though it does not differentiate itself from siblings like complete_task or reopen_task, which also touch status.

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?

No when-to-use or when-not-to-use guidance is given, and no alternatives are named. With siblings such as complete_task, reopen_task, and move_task, an agent could plausibly reach for update_task in cases where a dedicated tool is intended; the description leaves that ambiguity unresolved.

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