mark_task_status

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

Although annotations already declare non-readonly, destructive, idempotent, and closed-world behavior, the description adds important operational context: it bypasses the claim mechanism, specifies exact permission flags for status groups, and discloses board and Slack side effects with reason propagation.

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 front-loaded with purpose and valid statuses, then adds permission and side-effect details. Despite being dense, every clause contributes operational information and there is no 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 destructive, permission-gated mutation with side effects, the description covers statuses, override behavior, permission requirements, and board/Slack effects. The main gap is that as_agent is not explained, and there is no mention of return or error behavior beyond the side effects.

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 0%, so the description carries the burden. It compensates by listing allowed Status values and implying Reason is the supplied reason, but it omits any explanation of as_agent and gives no format or semantics beyond the status enumeration.

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 and resource: setting a task to a non-normal status. It enumerates the exact statuses and distinguishes this from normal task flow by noting it bypasses the claim mechanism via the override path.

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 gives clear usage context: non-normal statuses, an override path, and permission requirements per status group. However, it does not explicitly name alternatives such as override_verdict or release_claim, nor does it state when not to use this tool.

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