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

The annotations already flag destructiveHint=true and idempotentHint=true, and the description usefully qualifies that: the decision is *pending*, only an authorized human can accept it, and no external actions are authorized, so the agent knows a destructive-flagged call does not itself execute anything. That is real added context. However, it never explains what a 'canonical descriptor' or 'narrow' decision means, whether base_revision mismatch causes rejection, or what authorization the caller needs beyond 'authorized human' on the accept side.

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?

Two sentences, front-loaded with the creation action, with no filler. Every clause carries information. Slight deduction for undefined jargon ('narrow', 'canonical descriptor') that costs the reader a re-read without resolving meaning.

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 an 8-required-parameter, destructive, wide-world mutation with no output schema, the description covers the essential safety story (pending state, human gate, no external effects) but leaves real gaps: no return shape or receipt indication, no failure modes for revision conflicts, and half the parameters unexplained. Adequate to avoid misuse, not enough to call it confidently.

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 coverage is only 25% (room_id and client_id are the only documented properties), so the description has to carry weight. It gestures at three of the eight parameters: 'canonical descriptor' (base_revision), 'exact decision text' (decision_text), and 'source references' (source_numbers / source_receipt_ids). The mapping is loose rather than explicit, and owner_id, relay_id, and base_revision's concurrency role remain completely unexplained across both sources.

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: creates a *pending* human decision attached to an existing relay, built from the relay's canonical descriptor plus exact decision text and source references. The object created and its state are unambiguous. It does not, however, distinguish itself from the crowded set of similarly named siblings (propose_decision, purpose_propose_decision, propose, propose_poll_result), which an agent must otherwise disambiguate by schema inspection.

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 is only implied: the reader infers this is the path for escalating a concrete decision to a human on an existing relay, and that the relay must already exist ('for an existing relay'). There is no explicit when-to-use versus when-not, and no named alternative among the many propose_* siblings. The sentence about human acceptance describes the downstream workflow rather than selection guidance.

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