Set status

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

The description discloses numerous side effects not visible in annotations: writes to the work log, roll-up into velocity/metrics, pad snapshot refresh, owner stamping, ownership release, and uncommitted/commitReminder response behavior. It also clarifies failure semantics (mirror failure never blocks). This goes well beyond the annotations' basic non-read-only/non-destructive hints and does not contradict them.

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 purpose is front-loaded and the information is all relevant, but the description is a single dense paragraph with long clauses and internal ticket references, making it harder to parse than its complexity warrants. It could be split into short labeled sections without losing value.

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 15-parameter tool with no output schema, the description covers the most decision-critical behaviors: gates, overrides, ownership conflicts, git/commit handling, and side effects. It leaves return-shape details mostly implicit, but it does mention compact ack vs full ticket view and the uncommitted warning, so an agent has enough to call it safely.

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?

With only 67% schema coverage, the description adds meaningful context for approve and force (gate overrides and takeover semantics) and explains why completion metadata (model, tokens, additions, deletions) matters by linking them to the work log and metrics. Several parameters like handoff and learnings are left to the schema, but the schema already documents them well.

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?

Opens with a specific, unambiguous action: 'Move a task between Todo / In Progress / Review / Done,' which names both the verb and the exact resource scope. It also adds workflow detail (Review gating) that distinguishes it from general update_task-style siblings. This is more than a vague restatement of the tool name.

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 gives concrete conditions for behavior—requireReview, requireCommitOnDone, graduated projects, git-enabled projects, and multi-user ownership—so an agent knows when gates or side effects apply. It does not explicitly name sibling alternatives or state when not to use set_status, but the context is clear enough to select it for status transitions.

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