Edit message

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

Annotations only say destructiveHint=true, but the description discloses far more: the draft step is non-mutating, the confirm step is irreversible, chat/message_id/new_text/mentions are cross-validated at confirm and discrepancies rejected, foreign-message edits are server-rejected, and the edited message reads back with a non-empty LastEditTimestamp. This meaningfully extends what the annotations already provide, and there is no contradiction with destructiveHint=true.

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?

Three dense sentences arranged as cause-and-effect: draft behavior, confirm behavior with irreversibility and validation, then post-edit state. It is front-loaded with the most critical fact (two-step process, draft does not edit), and every clause earns its place — nothing repeats the schema or annotations.

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 complex six-parameter tool with no output schema, the description covers the whole call sequence, irreversibility, mismatch rejection, the own-message restriction, and the observable post-edit state (new text plus LastEditTimestamp). Small gaps remain: the confirm step's return value and error shapes are not described, and the draft preview's exact structure is only partially sketched — though the schema's detailed parameter documentation partially compensates.

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 100%, and the schema descriptions are already unusually rich — mentions documents the draft/confirm resolution and ordering rules, confirm explains the boolean switch, and confirm_token ties to the draft. The description contributes flow-level context (draft first, then confirm with token) but adds no parameter-specific meaning beyond the schema, so the baseline of 3 applies.

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+resource+scope constraint: 'Правка своего сообщения' (editing one's own message), and immediately explains the two-step draft/confirm mechanism. This distinguishes it from sibling tools like send_message, delete_message, and pin_message without needing to open their 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 usage context is explicit: a mandatory two-step sequence where 'без confirm возвращает превью ... и НЕ правит' but 'с confirm:true и confirm_token из превью правит'. It also states an exclusion — 'Правку чужого сообщения отклоняет сервер' — signaling not to use it on messages the agent didn't author. It falls short of explicitly naming alternatives (e.g., send_message for new messages), so it earns a 4 rather than a 5.

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