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

Annotations already declare the safe read profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description's contribution is the added context: results are ordered newest first, include unread counts and last-message previews, and — importantly — a disconnected account yields connection instructions rather than an empty list. That last detail is genuinely useful non-obvious behavior the annotations cannot convey.

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 compact sentences, front-loaded with what the tool returns, then how to use the ids, then the connection precondition. No filler or restatement of the title.

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?

An output schema exists so return values need not be re-explained, yet the description still flags the key field (`id`) and the failure mode. With 100% schema coverage and annotations, an agent has everything needed to call this correctly.

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%, so both `limit` (default 50, max 100) and `account` (label or id from telegram_list_accounts, default if omitted) are already fully documented in the schema. The description adds no parameter-level detail, which is the expected baseline when the schema 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?

States a specific verb and resource (lists Telegram chats) plus the entity types covered (people, groups, channels) and the payload shape (unread counts, last message preview, newest first). This cleanly separates it from the many sibling list tools such as signal_list_chats, whatsapp_list_chats and zalo_list_chats.

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?

Gives clear downstream context — the returned `id` is what telegram_read_messages, telegram_search_messages and telegram_send_message consume — and states the prerequisite that Telegram must be connected via telegram_connect. It does not, however, contrast itself against telegram_list_accounts or explain when searching (telegram_search_messages) is preferable to listing.

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