Telegram-mcp has 9 tools with basic schemas and descriptions, but significant gaps limit production readiness. All tools have descriptions (10-60 chars, mostly short), and input schemas are present with typed parameters. However, descriptions are often too terse to guide LLM selection (e.g., 'Send a message to a Telegram chat' lacks context on when to use vs. send_file or send_chat_action). Parameter descriptions are minimal, 'The Telegram chat ID' doesn't explain format or constraints. No output schemas documented. Error handling is absent from tool definitions. Permission-gated tools (ask, request_permission, broadcast_permission_request) lack clear guidance on expected responses or failure modes. Tool composition is reasonable (send_message, send_file, edit_message, react are distinct), but missing idempotency hints and recovery guidance.
Send a permission/confirmation prompt to the user via Telegram and wait for response
Broadcast a permission request to multiple users
Download a file from Telegram
Edit an existing message in a Telegram chat
Add an emoji reaction to a Telegram message
Request permission from the user for a specific tool or action
Send a chat action (typing, uploading, etc.) to indicate activity
Descriptions are too short (25-60 chars) to guide LLM tool selection. 'Send a message to a Telegram chat' doesn't explain when to use send_message vs. send_file, or what parse_mode does. Baseline for A-grade tools is 50-200 chars with context on WHEN and WHY.
No output schemas documented. LLMs cannot plan downstream calls or extract return values. E.g., send_message should document it returns {message_id, timestamp, chat_id} so agents can chain to edit_message or react.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 45 | <=2025-11-25 | v2 |
Send a file to a Telegram chat
Send a message to a Telegram chat
Permission-gated tools (ask, request_permission, broadcast_permission_request) lack error handling guidance. What happens if the user denies? Timeout? How should the agent retry? No recovery path documented.
Parameter descriptions are minimal. 'The Telegram chat ID' doesn't specify format (numeric string? @username?), constraints, or examples. 'The action type' for send_chat_action doesn't list valid values (typing, upload_photo, etc.), should be an enum.
No idempotency hints or destructive operation warnings. send_message, send_file, edit_message, react, and request_permission all modify state but lack toolAnnotations (destructiveHint, idempotentHint) to guide agent retry logic.