send_rich_message

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

Annotations already declare it is a non-destructive, open-world, non-idempotent write, so the description need not re-state safety. It adds real behavioral context beyond that: hard limits (32768 chars, 50 media), and the failure mode that media must be HTTP(S) URLs while file_id and local paths do not work. It stops short of describing what happens on partial failure or rate 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?

Four short sentences, front-loaded with the format identity, then the alternative, then the hard limits, then the prerequisite. Nothing is redundant or buried; each sentence changes what the agent would do next.

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?

The content-authoring side is well covered for a complex nested object with no output schema, so the agent knows how to build the post. But for a 12-parameter delivery tool, the entire set of routing/delivery options (thread, business connection, effects, reply markup, paid broadcast) is left unexplained, which is a meaningful gap in an otherwise strong definition.

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 only 42%, and the description adds almost nothing beyond the schema's own rich_message text — the limits and HTTP(S)-URL rule it repeats are already documented in the nested schema. Ten optional parameters (reply_markup, message_effect_id, message_thread_id, business_connection_id, direct_messages_topic_id, disable_notification, protect_content, allow_paid_broadcast, reply_parameters, suggested_post_parameters) get no meaning from either source.

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 and resource ('Send a rich message') and immediately pins down the format ('the long-form post format') plus the feature envelope (32768 characters, headings, tables, up to 50 inline media). This distinguishes it from the many other send_* siblings without requiring the agent to open 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?

It states an explicit alternative and the exact condition that selects it: 'Use this instead of send_photo when a post exceeds the 1024-character caption limit.' It also prescribes a prerequisite call ('Call telegram_format with topic "rich_message" ... before building the post'), which is actionable routing guidance rather than vague context.

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