update_status

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

The description adds meaningful behavioral context beyond annotations: it discloses an authorization requirement (holding the claim), an environmental requirement (target list exists), and rejection of illegal transitions. Annotations already indicate mutation and idempotence, and no contradiction exists.

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 three sentences: core action, legal transitions, and constraints. Every sentence is purposeful, front-loaded, and free of redundancy or filler.

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 two-parameter status transition tool, the description covers the action, allowed moves, preconditions, and rejection behavior. The presence of an output schema and annotations covers return values and mutability, leaving no major gaps.

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 covers both parameters with high coverage, but the description adds an important legal-move graph (todo -> in_progress -> review -> done plus in_progress -> todo) that the schema's status description does not provide. This helps the agent choose valid status transitions, going beyond the simple allowed-value list.

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 'Move a task you have claimed to a new status,' giving a specific verb and resource. It further defines legal moves (todo -> in_progress -> review -> done, plus in_progress -> todo), which clearly distinguishes this status-workflow tool from generic siblings like move_task or update_task_details.

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?

It explicitly states prerequisites ('You must hold the claim on the task, and the board must have a list for the target status') and says illegal jumps are rejected, which tells the agent when the tool applies. It does not explicitly name alternatives such as move_task for non-status repositioning, so it falls just short of full alternative guidance.

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