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

With no annotations, the description carries the full burden and does so well: it discloses the side-effect scope ('kept beside the design, like comments: it never moves the revision'), the authorship semantics (recorded as an agent's decision), the audience limitation relative to await_decision, and idempotency behavior. These are exactly the traits an agent needs before invoking a mutation-like record call.

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?

Four tight sentences, front-loaded with verb+resource and scope, then audience semantics, then the idempotency tip. Every sentence carries distinct information; nothing is repeated from the name or title.

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?

An output schema exists so return values need no explanation, and the description covers side effects, audience, and idempotency for a 9-parameter tool. The remaining gap is authorization context — the token/header interaction is left to the schema's token description rather than summarized here — which keeps it from a 5.

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 67% across 9 parameters, so the schema already documents the subtle ones (token, note, revision, agentName/agentModel). The description adds meaning only for decisionId (idempotency), which the schema also states, and names the two verdict values already in the enum. It does not compensate for the undocumented remainder, so baseline 3 is appropriate.

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 ('Record a review verdict — approve or reject — on one revision of a design') and immediately distinguishes it from the nearest sibling by noting it never moves the revision and does not satisfy ui_builder_await_decision's human waiter. An agent can separate this from post_comment, apply, and await_decision without opening a schema.

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 clear context for when this is the right call (recording an agent's verdict beside a design) and an explicit when-not: it will not answer a person waiting on ui_builder_await_decision with from: "human". It also states the retry condition (pass your own decisionId to make a retry idempotent). It does not name a direct alternative for the human-waiting case beyond the implication, so it falls short of a full routing rule.

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