ai-agent-channel

revise_message

Re-issue the body of a sent proposal on its existing message ID, so edits do not create new messages. Old votes become stale, the proposal reappears for acknowledgment, and changes stay auditable.

Instructions

Re-issue the BODY of a proposal you sent, on the same message id — the way to publish edition 2 of a draft. Do not send a new message for a changed text: a vote is bound to a message id and cannot follow the text, so every edit used to cost a new id plus a nudge to every role. One document produced 40 messages in ten hours that way, 31 of them still listed days later — a fifth of everything the channel had outstanding, from one day of one document. Votes cast on the previous text are QUENCHED, not deleted: they stay on record flagged 'stale', stop counting toward 'agreed', and the proposal reappears in those roles' awaiting_ack — they agreed to different bytes. The response and message_history carry the old and new sha256 of the body, so what changed is auditable without keeping a copy. Only the author may re-issue, and not after the proposal has approved a pin version (that would rewrite the text a pin says it was approved against). Topic may be updated along the way; recipients, kind and pin_key are fixed at send time — a different audience or a different pin is a different proposal.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`body`	No
`note`	No
`topic`	No
`body_ref`	No
`message_id`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 12, 2026

TDQS

A4.4/5.0

Behavior5/5

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: vote side effects (votes QUENCHED, flagged 'stale', stop counting toward 'agreed', roles re-added to awaiting_ack), the authorization prerequisite (author only), the prohibition after pin approval, and the fixed-vs-editable fields (topic editable; recipients/kind/pin_key fixed). It also notes the audit trail (old/new sha256) — far beyond what the bare schema offers.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The operative facts (what it does, when not to, vote consequence) are front-loaded, but the paragraph is padded with an anecdote about one document producing 40 messages — persuasive framing rather than invocation-critical detail. Every sentence should earn its place; this one is colorful but not needed to call the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

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 not be spelled out (though it helpfully notes sha256 auditing). For a mutation tool with no annotations, it covers authorization, prohibitions, and downstream effects well; the only shortfall is the undocumented 'note' and 'body_ref' parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 meaningfully clarifies message_id (same id, not new), body (the re-issued text), and topic (may be updated), but says nothing about the 'note' or 'body_ref' parameters, leaving two of five undocumented anywhere.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb and resource ('Re-issue the BODY of a proposal you sent, on the same message id') and frames it as editioning an existing draft rather than creating a new one. It explicitly contrasts with the intuitive-but-wrong path ('Do not send a new message'), which cleanly separates it from the send_message sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use ('to publish edition 2 of a draft'), when-not-to ('not after the proposal has approved a pin version'), and the governing condition ('Only the author may re-issue'). It also names the alternative it replaces (sending a new message) and why that is wrong.

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