Delete a Telegram message

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

Annotations already mark destructiveHint=true, so the description adds substantial value beyond that: it explains no preview exists because the Bot API cannot read a message back, that the result is Telegram's own success answer rather than a verified read-back, and details two vendor constraints. It also discloses the confirm requirement and the 'permanent' nature. This is rich behavioral context.

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 serves a purpose: safety flow, no-preview rationale, vendor limits, parameter mapping, credits, and connector requirement. It is front-loaded with the core action and safety warning, and while lengthy, it is succinct given the number of critical details an agent needs.

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 destructive tool with no output schema, the description covers everything an agent needs: prerequisites, parameter sources, safety confirmation step, vendor limitations, expected return behavior, and credit cost. Nothing critical is left to guesswork, making it complete for correct invocation.

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 100%, so baseline is 3. The description adds valuable context beyond the schema: it explains chatId is the same as used in post_to_telegram, messageId is the one returned by post_to_telegram (also the t.me link number), and reinforces that confirm is required true. This bridges the tool to its companion and clarifies provenance of values.

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 states a specific action ('PERMANENTLY delete one message'), the resource ('a Telegram chat'), and the scope ('the bot posted'). It clearly differentiates from sibling deletion tools like delete_x_post and delete_bluesky_post by specifying Telegram and the bot's own messages.

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?

Explicitly explains the safety flow (call without confirm first to preview the sentence, then confirm), vendor limits (48-hour window, channel permission), and how to obtain parameters (same chatId as post_to_telegram, messageId returned by it). Also states prerequisites (Telegram connected) and credit cost. This leaves no doubt about when and how to invoke.

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