Telegram MCP Server

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

Annotations cover key traits (not read-only, open-world, idempotent, non-destructive), but the description adds valuable context beyond this: it explains the incremental sync behavior, local storage path ('data/raw/{chat_id}/'), and that it handles both messages and media. It doesn't mention rate limits or authentication needs, but provides useful operational details.

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 appropriately sized and front-loaded, starting with the core functionality. Every sentence adds value: the first explains the action, the second covers incremental sync, the third specifies storage location, the fourth positions it among tools, and the fifth clarifies parameter usage. It could be slightly more concise by combining some points.

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 the tool's complexity (sync operation with media handling), annotations provide good safety/behavioral coverage, and the description adds operational context. However, without an output schema, it doesn't describe return values or error conditions, which leaves a minor gap. Overall, it's mostly complete for effective use.

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 the schema already documents both parameters well. The description adds some context by explaining the effect of omitting 'since_date' ('for full sync or incremental from last sync'), but doesn't provide additional syntax or format details beyond what the schema specifies. This meets the baseline for high schema coverage.

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 clearly states the specific action ('downloads all messages and media files from a chat to local storage') and distinguishes it from siblings by emphasizing it's the 'main tool for extracting chat data including photos and documents.' It explicitly mentions what it does (full sync with incremental capability) and what resources it handles (messages, media files).

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 provides clear context on when to use it ('main tool for extracting chat data') and how to control sync behavior with 'since_date'. However, it doesn't explicitly state when to use alternatives like 'telegram_get_history' or 'telegram_download_media', which could help differentiate further among siblings.

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