Loading ToolBench
Multi-tenant Telegram gateway for AI agents — HTTP+stdio transport, 8 agent-optimized tools, MTProto User API
fast-mcp-telegram provides 8 well-structured tools with comprehensive input schemas and detailed descriptions. Most tools include parameter type definitions, enums for constrained inputs, and context-aware guidance. However, output schemas are not explicitly documented in the source, descriptions vary in completeness, and some parameter relationships lack clarity. Error handling patterns and recovery guidance are present but not uniformly applied across all tools. The server demonstrates solid foundational quality with room for improvement in output schema documentation and consistency.
Replace the text of an existing message in a Telegram chat. Only works on messages sent by the authenticated account. Cannot edit media or other message attributes — text only. parse_mode: classic markdown/html/auto or rich (Rich Message; dialect auto-detected). Success: dict with message_id, date, chat, text, status='edited', and edit_date (rich messages also set rich=true and rich_format). Error: dict with ok=false and error string (e.g. message not found or not editable). Use edit_message to update a previously sent message; use send_message to create new ones. Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md
Find users/groups/channels by name, username, or phone. Comma-separated usernames are searched in parallel and results are merged round-robin. Global search (query required) searches all Telegram; with min_date, max_date, or filter, search uses dialog list or a named filter; include_peers filters use last-activity from GetPeerDialogs; flag-based filters use dialog list dates. Success: dict with key chats (list of chat objects). Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md
Load profile and metadata for one user, bot, group, or channel. Success: info dict; forum chats may include topics up to topics_limit; user targets may include common_chats up to common_chats_limit. Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md
Output schemas not explicitly documented in source code. Tools return structured responses but the exact fields, types, and pagination behavior are not formally specified in the visible schema definitions.
invoke_mtproto tool is a low-level passthrough that exposes raw MTProto API with minimal guardrails. Named 'invoke_mtproto' (generic verb), lacks domain-specific guidance, and description does not explain when to use it vs higher-level tools. Violates single-responsibility principle and creates security risk with 'allow_dangerous' flag requiring explicit opt-in.
Parameter relationships underdocumented. get_messages has mutually exclusive parameters (message_ids vs query vs reply_to_id, context vs include_replies) mentioned in text description but not formally specified. thread_scope only applies with reply_to_id; this dependency is stated but could be clearer. LLMs may pass invalid combinations.
Inferred effective spec: 2026-07-28+.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | B | 73 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 0 | - | v1 |
Read or search messages in one chat: browse latest, search text, fetch by ids, or load replies to a message (comments, forum topics, threads). Use from_user to filter by sender (server-side, per-chat only). Use context to include neighboring messages and reply chains around each result. Use include_replies to fetch up to 5 direct replies per result. Do not combine message_ids with query or reply_to_id. Success: messages, has_more, optional total_count and discussion fields. Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md
Low-level Telegram API (MTProto) invoke for methods not wrapped by other tools. Dangerous methods require allow_dangerous=true. Success: API result dict or normalized error. Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md
Search all Telegram chats at once (not scoped to one chat). Comma-separated query terms; optional filters by date, chat kind, and public username. Success: message list and metadata dict. Global search ignores include_total_count. Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md
Send text and optional file attachments to a Telegram chat. Supports reply-to (including forum topics and channel discussion groups), parse_mode: classic markdown/html/auto (entities) or rich (Rich Message document; dialect auto-detected). parse_mode=rich cannot be combined with files. File attachments as http(s) URLs, local paths, or data: URIs. When files are provided, the message text becomes a caption. For channel posts with reply_to_id, automatically posts in the linked discussion group. Success: dict with message_id, date, chat, text, status='sent', and sender info (rich messages also set rich=true and rich_format). Error: dict with ok=false and error string. Use send_message to create new messages; use edit_message to modify existing ones. Use send_message_to_phone when targeting a phone number instead of a chat_id. Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md
Send to a phone number: may create a temporary contact, then send text or files. Supports parse_mode: classic markdown/html/auto or rich (Rich Message; dialect auto-detected). parse_mode=rich cannot be combined with files. Success: send result plus contact_was_new / contact_removed when applicable. Full documentation: https://github.com/alexeyleshchenko/fast-mcp-telegram/blob/main/docs/Tools-Reference.md
Pagination behavior inconsistent. search_messages_global and get_messages both mention 'limit' and 'has_more' in descriptions but do not formally specify cursor/offset semantics or how to paginate through results. Agents need clear pagination patterns (limit + offset, cursor, or next_token) in schema.
Error handling guidance limited. Descriptions mention success cases and some error scenarios (e.g., 'message not found') but do not systematically classify errors as retryable, user-fixable, or fatal. Missing recovery hints like 'Try search_users() if the chat is not found.'
Description of 'from_user' in get_messages is lengthy (295+ chars) and includes multiple resolution methods (bare strings, usernames, phone, numeric IDs, t.me URLs). While informative, this violates the 10 - 1024 char guideline for parameter descriptions and could be simplified with an enum or referenced external doc.
Parameter 'chat_types' and 'public_chats' filters are described separately but interact in non-obvious ways. Documentation states 'public_chats does not apply to private DMs' but the intersection of filters and behavior is not fully spelled out. LLMs may misconstrue filter semantics.