telegram_edit_message_caption

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

Annotations already signal idempotence and non-destructiveness, so the description adds value by disclosing the media-only constraint, inability to change the photo, and the requirement that the bot be the original sender with edit permissions. These are important behavioral nuances beyond what annotations convey. No contradiction with annotations.

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 well-structured with an opening purpose, a short 'use this' paragraph, and clear Args/Returns sections. It is slightly longer than strictly necessary but every sentence provides useful information, so the verbosity is earned. The front-loading of purpose and constraints is effective.

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?

Given 5 parameters, no schema descriptions, and the presence of an output schema, the description covers all necessary aspects: prerequisites, limitations, parameter semantics, and return format. It even explains the response_format behavior. The tool is complex enough that this level of detail is warranted, and the description completes the picture beyond the annotated fields.

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 0%, the description fully compensates by detailing every parameter: channel_id is given with examples and a constraint, message_id source is explained, new_caption includes max length and formatting support, parse_mode lists options with a default, and response_format is clarified. This adds substantial meaning beyond the bare schema types.

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: 'Edit the caption of an existing photo message in a Telegram channel.' It clearly differentiates from siblings like telegram_publish_photo (publishing) and telegram_edit_message (likely editing message text) by focusing on captions of media messages. The scope is unambiguous.

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 the tool ('modify the caption text of a previously published photo message'), explicitly limits usage to media-containing messages, and notes that the bot must be the original sender with edit permissions. It does not explicitly name an alternative tool for non-media messages, but the 'only works for media' phrasing implies when not to use it. This provides solid context without being overly verbose.

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