Update task status

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

With no annotations present, the description carries the full burden and delivers richly: it discloses that the completion record becomes 'the permanent, queryable design record in .hub/tasks/' that 'feeds get_handoff_brief,' and that uncommittedFileWarnings means the listed files are 'NOT actually committed/pushed yet.' It also reveals the social consequence of abandoning versus silently leaving a task in_progress, which the schema and annotations do not convey. No contradiction with annotations.

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?

Roughly 200 words, but the tool has conditional behavior, a nested object, and a side-effect warning, so the length is largely earned. It front-loads the core purpose and highest-stakes rule (done → completion) before the abandon guidance. Some rationale prose, such as 'unlike prose that gets reinterpreted differently by every reader,' is verbose but reinforces a constraint worth emphasizing.

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 state-transition tool with nested parameters and no annotations or output schema, the description covers the essential ground: required shapes, persistence, handoff integration, and the commit warning. The main gaps are the undocumented memberName parameter and no statement of what a successful update returns. An agent still has enough to call it correctly in the common and risky cases.

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 only 40%, so the description must compensate, and it does for the consequential parameters: it defines the fixed shape of completion (whatWasBuilt, decisions, filesChanged, knownLimitations, nextSteps) and the meaning of 'done' and 'abandoned' states. It does not touch memberName, which remains unexplained in both schema and description, though taskId is self-evident and the gap is limited.

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?

States a specific verb and resource ('Update a task's status') and goes on to define the two status transitions that carry real consequences ('done' with completion, 'abandoned' with abandonReason). The description makes the tool's scope unambiguous against siblings like update_plan, claim_task, and log_activity by the resource it mutates, even without naming them.

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?

Gives explicit conditional guidance: 'When marking a task done, ALWAYS include completion' and 'If you're changing direction WITHOUT finishing... set status abandoned with abandonReason instead of just going quiet.' It also warns against silently leaving a task in_progress indefinitely. It does not name alternative tools or state when to prefer a sibling such as log_activity, so it stops short of a 5.

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