revise_message

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

No annotations are provided, so the description carries the full burden—and it delivers. It discloses that previous votes are 'QUENCHED, not deleted,' flagged 'stale,' stop counting toward 'agreed,' and cause the proposal to reappear in awaiting_ack. It also exposes auditability via old/new sha256, permission constraints, the pin-approval restriction, and the fact that recipients/kind/pin_key are fixed at send time.

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 dense but every sentence contributes a distinct, operationally relevant fact. It front-loads the core action and then layers on state effects, audit, permission, and immutability constraints. There is no repetition or 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 mutation tool with no annotations and five undocumented parameters, this description is unusually complete: it covers state changes, permissions, timing restrictions, auditability, and update scope. The only notable omission is body_ref semantics, which keeps it from being fully complete. An output schema exists, so return-value documentation is already handled elsewhere.

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 must compensate. It does clarify body as the re-issued text, note's max length, and that topic 'may be updated along the way.' However, body_ref is never explained, and the relationship between body and body_ref is ambiguous. With five parameters and no schema descriptions, this partial coverage leaves a real gap.

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 opens with a specific verb and resource: 'Re-issue the BODY of a proposal you sent, on the same message id.' It also explicitly frames this as 'the way to publish edition 2 of a draft instead of sending a new message,' which distinguishes it from sibling tools like send_message. An agent can immediately understand the tool's unique function without inspecting other schemas.

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?

The description states when to use this tool ('the way to publish edition 2 of a draft instead of sending a new message') and when not to: 'Only the author may re-issue, and not after the proposal has approved a pin version.' It also clarifies that a different audience or pin means 'a different proposal,' implying a new message should be sent instead. This gives both positive and negative usage guidance.

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