editMessageCaption

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

With no annotations provided, the description carries the full disclosure burden. It does surface one genuinely useful behavioral trait — the divergent return value for inline messages (True instead of the edited Message). However, it stays silent on prerequisites (bot must have sent the message or hold edit rights), failure conditions, and the fact that only the caption is modified while media/text remain untouched.

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?

Two sentences with zero filler. The core operation is front-loaded, and the return-value caveat follows immediately; both sentences earn their place.

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 9-parameter mutation tool with no annotations and no output schema, the description is thin. It omits the conditional addressing requirement (chat_id+message_id XOR inline_message_id), which an agent would only discover by reading schema parameter descriptions, and offers no guidance on supported message types or when editing is not permitted. The return-value disclosure partially compensates, but an agent reading the description alone would miss key invocation preconditions.

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 parameter descriptions are rich (e.g., 'Required if inline_message_id is not specified', @channelusername format, and the media-type constraint on show_caption_above_media). The tool description adds no parameter-level meaning, but at full coverage the baseline of 3 applies — the schema already does the heavy lifting.

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 the specific operation 'Edit captions of messages' — a precise verb+resource pairing that distinguishes it from the many sibling edit tools (editMessageText, editMessageMedia, editMessageReplyMarkup). It also discloses the return contract (edited Message vs True for inline messages), removing ambiguity about what the caller receives.

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 purpose statement implies the use case — changing a message's caption — but it never explicitly routes the agent away from siblings like editMessageText, nor does it flag the mutually exclusive addressing modes (chat_id+message_id vs inline_message_id). No alternatives or exclusions are named; the guidance is only implied.

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