tasks_update

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

Annotations already indicate idempotentHint=true (safe to retry) and destructiveHint=false. The description adds crucial behavioral context: the tool accepts multiple identifier types (UUID, short_id, title) and the response includes a dashboard URL that must be shown to the user. This goes beyond what annotations provide, though it could mention potential errors or authorization needs.

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 description is extremely concise at two sentences. The first sentence lists the updatable fields, and the second provides critical usage details (identifier flexibility and required user-facing output). No wasted words; every sentence adds value. It is well-structured and front-loaded.

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 tool's complexity (8 optional params, no output schema), the description covers the core purpose, identifier flexibility, and a key output behavior. It does not discuss error handling or side effects like whether changing assignee requires collaboration, but with annotations and schema already covering safety hints, it is largely complete for an agent to use 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 100% with each parameter already described in the schema. The description reinforces that 'tags' replaces existing tags and that the 'identifier' parameter can take multiple forms, but does not add substantial new meaning beyond the schema descriptions. A score of 3 reflects the baseline for high coverage with minor added context.

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 clearly states the verb 'update' and the resource 'task', and lists specific fields that can be updated (title, description, status, priority, tags, due date, assignee). It implicitly distinguishes from sibling tools like tasks_assign (only assignee), tasks_resolve (only status), and tasks_add_comment (only comment) by covering multiple fields, making its purpose unambiguous.

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 does not provide explicit guidance on when to use this tool versus alternatives. It mentions that it accepts any identifier (UUID, short_id, or title), which is useful for invocation, but lacks advice on when to prefer tasks_update over tasks_assign or tasks_resolve. The intent is implied but not directly stated.

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