messages_update

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

Annotations already mark this as a non-read-only, non-destructive write, but the description adds real operational context: read the message first, omitted fields and existing attachments are preserved, new files are appended, changes are verified independently, and a one-time approval_id/payload_hash contract bound to channel_id and message_id is required. That is substantial disclosure beyond the annotations, though the 'polls and TTS cannot be edited' limit clashes with the poll/tts properties present in the schema, which weakens confidence in the stated limits.

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 bolded section labels (Purpose, When to use, Limits, Approval, Returns) front-load the essential information and each block carries distinct content with no filler. It is denser than average for a tool description, but every sentence maps to a decision the caller has to make.

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 12-parameter, nested-object, approval-gated mutation with an output schema already present, the description covers purpose, prerequisites, preservation semantics, approval flow, and success/failure outcomes without needing to restate return values. The remaining gap is that it neither resolves the poll/TTS schema contradiction nor differentiates itself from messages_edit.

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?

With schema description coverage at only 42%, the description carries much of the burden and does so for the important cases: message_id is framed as a 'receipt', the three __confirm* parameters are explained as a one-time approval triple tied to channel_id/message_id, and files are described as appended with filenames distinct from retained attachments (a constraint the schema's pattern does not express). It still says nothing about allowed_mentions or components, and the tts/poll parameters are contradicted rather than documented.

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 gives a specific verb+resource+scope: 'Update one rich announcement previously authored by this bot,' which usefully narrows the target to rich bot-authored messages. However it never names or distinguishes itself from the obvious siblings messages_edit or messages_publish, leaving the agent to infer the boundary from the 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?

The 'When to use' line gives concrete triggering conditions (correct an announcement, replace embed/layout content, attach another file) and the required receipt message_id. It lacks an explicit counterpart such as 'for plain-text edits use messages_edit,' so routing between the two similar tools still requires inference.

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