update_adr_status

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

With no annotations provided, the description carries the full disclosure burden and does it well: it exposes validation behavior (rejects unknown statuses), preconditions (target ADR must exist for superseding), and a destructive side effect (removes the 'ADR Review Discussion' section once 'Accepted' is reached). It stops short of describing failure/error behavior or permissions, which keeps it below a 5.

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 core action is front-loaded ('Transition one ADR's Status') and every guardrail clause carries distinct information with no redundancy. It is dense — a single long sentence — but the semicolon-separated enumeration keeps the overload reasonable for a tool with this many behavioral rules.

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?

Everything needed to invoke the tool correctly is present: valid statuses, precondition checks, the destructive side effect, and the cross-parameter dependency on 'explanation'. With no output schema, the missing piece is return-value semantics — the description never says what a successful transition returns — though the auto_reindex schema hint partially addresses the response shape.

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 100%, with all five parameters fully documented in the schema, establishing the baseline of 3. The description's mention of the 'explanation' requirement largely restates the schema's own description of that parameter, adding no new semantic content beyond cross-referencing it.

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 the action precisely — 'Transition one ADR's Status' — with singular scope and a lifecycle-management framing that the guardrails reinforce. It is clearly distinguishable from read_adr_status (read-only) and from edit_adr/create_adr, which are general-purpose rather than status-transition-specific.

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?

Usage context is implied rather than stated: the guardrails tell an agent what must be true before calling a transition (target ADR exists for 'Superseded by ADR-XXXXX', Decision section or explanation for 'Accepted'). However, no alternative tool is named explicitly and no when-not-to-use condition is given, leaving an agent to infer that edit_adr is the route for non-status changes.

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