MCP/HTTP Telegram Gateway — Multi-tenant, MTProto User API, 8 tools, multi-user Bearer auth, global search, session ACL, Docker
Each tool has a clearly distinct purpose: edit vs send, per-chat vs global search, user lookup vs info retrieval, and a low-level fallback. No overlap in functionality.
All tool names follow a consistent verb_noun snake_case pattern (e.g., send_message, get_chat_info, search_messages_globally), making it predictable for agents.
8 tools cover the essential Telegram operations without bloat. The count is appropriate for a focused MCP server, neither too few nor too many.
Core operations like send, edit, search, and info retrieval are covered. Minor gaps exist (e.g., no delete or forward message), but the set handles common workflows well.
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
| Name | Required | Description | Default |
|---|---|---|---|
| chat_id | Yes | Target chat: numeric id (e.g. -100…), username without @, or 'me' for Saved Messages. | |
| message | Yes | Message text. When sending files, used as caption. | |
| message_id | Yes | Message id in this chat to edit (from get_messages or Telegram). | |
| parse_mode | No | 'markdown'/'html'/'auto': classic entity formatting (auto detects). 'rich': Telegram Rich Message document; dialect auto-detected (known HTML tags outside code → rich HTML, else rich markdown). Default is 'auto'. parse_mode='rich' cannot be combined with files. | auto |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| chat | No | |
| code | No | |
| date | No | |
| rich | No | |
| text | No | |
| error | No | |
| action | No | |
| params | No | |
| sender | No | |
| status | No | |
| topic_id | No | |
| edit_date | No | |
| exception | No | |
| operation | No | |
| error_code | No | |
| message_id | No | |
| rich_format | No | |
| reply_markup | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (openWorldHint, idempotentHint, destructiveHint), the description discloses important behavioral traits: it only works on the authenticated account's own messages, cannot edit media (text-only), explains parse_mode behavior including rich message dialect auto-detection, and describes success/error response structures with specific fields. It also notes that 'parse_mode="rich" cannot be combined with files' in the schema, but the description adds operational context about response formats and error scenarios, significantly enhancing transparency.
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 information-dense but well-structured. It starts with the primary purpose, then constraints, parameter semantics, return values, usage guidance, and a documentation link. While slightly lengthy, every sentence provides relevant context. It earns a 4 for being comprehensive without excessive wordiness, though it could be trimmed slightly by omitting the full response schema description if an output schema is present.
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 (4 parameters, output schema present, annotations present), the description is remarkably complete. It covers purpose, restrictions, parameter behavior, success/error outputs, and usage guidance. The inclusion of specific error examples and the rich message format details ensures the agent can confidently invoke and interpret results. The documentation link provides additional fallback. This meets the highest standard of contextual completeness.
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 100% with detailed parameter descriptions, so baseline is 3. The description adds value by clarifying that the 'message' parameter is text-only (correcting a potential misinterpretation from the schema's 'When sending files, used as caption'), and it summarizes parse_mode options with the rich dialect auto-detection. This goes beyond pure schema repetition, thus a 4 is appropriate.
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 tool's function: 'Replace the text of an existing message in a Telegram chat.' It specifies the resource (messages in Telegram chats), the action (replace text), and distinguishes from siblings by explicitly noting 'Use edit_message to update a previously sent message; use send_message to create new ones.' It also clarifies scope limitations: 'Only works on messages sent by the authenticated account' and 'Cannot edit media or other message attributes — text only.'
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 explicit guidance on when to use the tool: 'Use edit_message to update a previously sent message; use send_message to create new ones.' It also implies when not to use it by stating 'Cannot edit media,' effectively directing media editing/sending elsewhere. This is clear and actionable, going beyond mere implication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum chats to return (recommended 50 or less). | |
| query | No | Name, username (no @), phone (+country…), or comma-separated usernames for batch lookup. Example: 'alice,bob,charlie'. Required for global search unless you use min_date/max_date or folder alone. | |
| folder | No | Telegram folder name (case-insensitive exact match after normalization). In Telegram's UI these are called folders; internally they are "dialog filters" — saved filter presets that group chats by custom criteria (pinned, unread, business, etc.). See Filters-vs-Folders.md for the technical distinction. | |
| public | No | If true, prefer chats with a public username; if false, without. Does not apply to private DMs. Omit to skip this filter. | |
| max_date | No | Inclusive maximum date filter (ISO 8601 date or datetime). Omit for no upper bound. | |
| min_date | No | Inclusive minimum date filter (ISO 8601 date or datetime). Omit for no lower bound. | |
| chat_type | No | Comma-separated chat kinds: private, bot, group, channel. Case-insensitive; extra spaces allowed. |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| code | No | |
| chats | No | |
| error | No | |
| action | No | |
| params | No | |
| exception | No | |
| operation | No | |
| error_code | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses useful behavioral details like parallel comma-separated search, round-robin merging, and mode switching based on parameters, adding value beyond the readOnly/idempotent annotations. However, it references parameters (include_peers, flag-based) that do not exist in the input schema, which undermines transparency and adds confusion.
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 moderately concise with a clear front-loaded purpose, but includes technical jargon (GetPeerDialogs, flag-based filters) and references to undocumented parameters, making it less clear than it could be. Every sentence has some content, but some could be streamlined or clarified.
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 tool is complex with multiple search modes, and the description references parameters not present in the schema, creating ambiguity about how to properly invoke the tool. The output schema exists and the return format is mentioned, but the mismatch between description and schema leaves significant gaps in understanding.
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?
The input schema documents all 7 parameters with descriptions, so baseline is 3. The description adds some context about batch lookup and search modes, but does not compensate for the phantom parameters mentioned. It adds marginal value beyond the schema's already-good parameter descriptions.
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 tool finds users/groups/channels by name, username, or phone, which is specific and distinguishes it from message-searching siblings. The verb 'Find' and resource 'users/groups/channels' are unambiguous.
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 conditional behavior for different search modes (global vs dialog list) but does not explicitly state when to prefer this tool over alternatives like search_messages_globally. It implies usage scenarios but lacks explicit exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| chat_id | Yes | Target chat: numeric id (e.g. -100…), username without @, or 'me' for Saved Messages. | |
| topics_limit | No | Max forum topics to list when the chat is a forum. |
| Name | Required | Description |
|---|---|---|
| id | No | |
| ok | No | |
| code | No | |
| error | No | |
| phone | No | |
| title | No | |
| action | No | |
| is_bot | No | |
| params | No | |
| topics | No | |
| is_user | No | |
| is_forum | No | |
| is_group | No | |
| username | No | |
| exception | No | |
| last_name | No | |
| operation | No | |
| error_code | No | |
| first_name | No | |
| is_channel | No | |
| common_chats | No | |
| topics_has_more | No | |
| participants_count | No | |
| common_chats_has_more | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it notes that the result may include topics up to topics_limit for forums and common_chats up to common_chats_limit for user targets, which is not fully captured by the schema. It also states the success return shape.
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 two sentences, front-loaded with purpose, and includes a documentation link. Every sentence earns its place, providing key behavior details without redundancy or fluff.
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 low complexity, rich annotations (readOnly, openWorld, idempotent), a full output schema, and a documentation link, the description is complete. It covers the main behavioral nuances (topics_limit, common_chats_limit) and success condition, so no critical information is missing.
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 baseline is 3. The description does not add meaning beyond the schema; it merely mentions topics_limit in a sentence, which repeats the schema description. The chat_id parameter is fully defined in the schema.
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 uses a specific verb ('Load') and resource ('profile and metadata for one user, bot, group, or channel'), clearly distinguishing it from siblings like get_messages (which retrieves messages) and find_chats (which searches chats). It precisely defines the tool's scope.
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 implies when to use this tool: whenever you need profile/metadata for a specific chat target. It provides clear context but does not explicitly mention exclusions or alternatives. However, the sibling tool list makes the differentiation obvious, so this is a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum messages to return (recommended 50 or less). | |
| query | No | Search within this chat only; comma-separated terms. Omit to browse latest or use message_ids / reply_to_id modes. | |
| chat_id | Yes | Target chat: numeric id (e.g. -100…), username without @, or 'me' for Saved Messages. | |
| context | No | Number of surrounding messages to include as context for each search result. 0 = disabled (default). 1-10 = include N messages before and N after each result. Also fetches the message being replied to and top replies (if include_replies=true). Requires chat_id. Disabled when result count exceeds cost-based caps. | |
| max_date | No | Inclusive maximum date filter (ISO 8601 date or datetime). Omit for no upper bound. | |
| min_date | No | Inclusive minimum date filter (ISO 8601 date or datetime). Omit for no lower bound. | |
| from_user | No | Only return messages from this sender. Not a display-name or contact-name search — bare strings resolve like chat_id via get_entity (usernames are case-insensitive and may match an unrelated channel). Prefer @username, phone (+…), or numeric user id. Also accepts 'me', 'self', t.me URL, -100 prefixed id. Uses Telegram's native from_id server-side filter (per-chat search only). | |
| message_ids | No | Exact message ids to fetch. Mutually exclusive with query and reply_to_id. | |
| reply_to_id | No | Anchor message id: channel post id, forum topic_id from get_chat_info, or a message id for direct replies. Use with thread_scope. | |
| thread_scope | No | Only with reply_to_id. auto: full forum topic (topic_id) or channel comment thread via getReplies; else direct replies. full: nested branch under a message id (forum in-topic uses search window, not whole topic); supergroup threads use search top_msg_id. direct: immediate replies only. | auto |
| include_replies | No | If true, fetch up to 5 direct replies per search result and attach as replies. Each result costs one API call (not batchable). Default: false. | |
| auto_expand_batches | No | Extra search batches to run when filters narrow results. Higher values may return more matches at the cost of latency. | |
| include_total_count | No | If true, response may include total_count where supported (per-chat search; ignored for global search). |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| code | No | |
| error | No | |
| action | No | |
| params | No | |
| _warning | No | |
| has_more | No | |
| messages | No | |
| exception | No | |
| operation | No | |
| error_code | No | |
| total_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description doesn't need to restate safety. It adds valuable details like 'include_replies to fetch up to 5 direct replies', the mutual exclusion constraint, and the success field list ('messages, has_more, optional total_count and discussion fields'). It also points to full documentation, enhancing transparency. This goes well beyond the annotations without contradicting them.
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 a tightly packed paragraph of about 120 words. It front-loads the core purpose, then gives parameter guidance in order of relevance, ends with success fields and a docs link. Every sentence conveys actionable info—no filler, no redundancy. The structure flows logically from 'what it does' to 'how to use it' to 'what to expect'.
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 has 13 parameters, an output schema, and multiple modes (browse, search, fetch by ids, replies), the description covers the essential usage scenarios and constraints. It mentions the success response shape and links to full docs for edge cases. The presence of a rich output schema means the description doesn't need to repeat field details, yet it still summarizes what the caller should expect. This is complete for a tool of this complexity.
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?
The schema has 100% coverage with detailed per-parameter descriptions, so the baseline is 3. The description elevates this by explaining how parameters work together (e.g., 'Use context to include neighboring messages and reply chains around each result', 'Use include_replies to fetch up to 5 direct replies per result'), and clarifies positional semantics like 'Use reply_to_id with thread_scope' (implicitly). It also states the per-chat limitation of from_user. This adds integrative meaning beyond the schema.
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?
Description opens with 'Read or search messages in one chat' followed by explicit modes: 'browse latest, search text, fetch by ids, or load replies to a message'. This clearly distinguishes it from siblings like search_messages_globally by scoping to a single chat. The verb 'Read or search' is specific and the resource ('messages in one chat') is unambiguous.
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 concrete usage guidance for several parameters ('Use from_user to filter by sender', 'Use context to include neighboring messages', 'Use include_replies to fetch up to 5 direct replies') and warns against invalid combos ('Do not combine message_ids with query or reply_to_id'). It stops short of explicitly naming alternative tools, though the 'in one chat' scope implicitly contrasts with global search. This is strong guidance but lacks a direct 'when not to use' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| resolve | No | If true, resolve string/int peer-like fields to TL Input* entities before invoke. | |
| params_json | Yes | JSON object string of TL parameters as in Telegram API docs; nested TL uses "_": "typeName" discriminator. | |
| allow_dangerous | No | If false, destructive methods (e.g. deletes) are blocked. Set true only when intended. | |
| method_full_name | Yes | Telegram API method, e.g. "messages.GetHistory" or "users.GetFullUser" (normalization applied). |
| Name | Required | Description |
|---|---|---|
| _ | No | |
| id | No | |
| ok | No | |
| code | No | |
| date | No | |
| chats | No | |
| error | No | |
| users | No | |
| action | No | |
| params | No | |
| result | No | |
| messages | No | |
| exception | No | |
| operation | No | |
| error_code | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description complements the destructiveHint annotation by explaining that dangerous methods require allow_dangerous=true, and discloses success/error return behavior. It also points to full documentation for deeper context, though it could elaborate on what 'normalized error' means.
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 sentences front-load the core purpose, then address safety and results, and finish with a documentation link. No wasted words; succinct and well-structured.
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, the presence of an output schema, and annotations, the description sufficiently covers the main usage scenarios and danger gating. The documentation link compensates for any missing details, though a brief example or note on normalization would make it fully complete.
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?
The input schema already provides comprehensive descriptions for all four parameters, including the discriminator convention for nested TL objects. The description adds only minimal value beyond the schema, mainly reinforcing the allow_dangerous behavior, so the baseline of 3 applies.
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 that this is a low-level Telegram API (MTProto) invocation tool for methods not wrapped by other tools, which separates it from siblings like send_message or get_messages. The verb 'invoke' and resource 'MTProto' are specific and unambiguous.
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 explicitly says to use this tool for methods not covered by other tools, providing clear guidance on when to invoke it versus using wrapped alternatives. The danger caveat about allow_dangerous=true adds practical usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum messages to return (recommended 50 or less). | |
| query | Yes | Search terms, comma-separated for multiple terms (OR-style global search). Required. | |
| public | No | If true, prefer chats with a public username; if false, without. Does not apply to private DMs. Omit to skip this filter. | |
| max_date | No | Inclusive maximum date filter (ISO 8601 date or datetime). Omit for no upper bound. | |
| min_date | No | Inclusive minimum date filter (ISO 8601 date or datetime). Omit for no lower bound. | |
| chat_type | No | Comma-separated chat kinds: private, bot, group, channel. Case-insensitive; extra spaces allowed. | |
| auto_expand_batches | No | Extra search batches to run when filters narrow results. Higher values may return more matches at the cost of latency. | |
| include_total_count | No | If true, response may include total_count where supported (per-chat search; ignored for global search). |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| code | No | |
| error | No | |
| action | No | |
| params | No | |
| _warning | No | |
| has_more | No | |
| messages | No | |
| exception | No | |
| operation | No | |
| error_code | No | |
| total_count | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is known. The description adds a useful behavioral quirk: global search ignores include_total_count, and it clarifies that success returns a message list and metadata dict, which supplements the output schema.
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 front-loaded with the core purpose, then concisely lists key features and a behavioral caveat, and ends with a documentation link. Every sentence earns its place with no redundant or vague content.
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 8 parameters, a rich schema, an output schema, and annotations, the description provides sufficient context including global scope and the include_total_count quirk. It could be more explicit about alternatives to scoped search, but no critical information is missing.
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?
With 100% schema description coverage, all 8 parameters are fully documented in the schema. The description restates comma-separated terms and optional filters but adds no new parameter semantics beyond what the schema already provides; the include_total_count caveat is already present in the schema.
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 identifies the tool as performing a global search across all Telegram chats, explicitly noting it is not scoped to one chat. This verb-resource-scope combination distinguishes it from sibling tools like get_messages that are chat-specific.
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 gives clear context that this is for searching across all chats at once, contrasting with scoped search. However, it does not explicitly name alternative tools for scoped searches or state when not to use this tool, leaving a small gap in guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | List of attachment URLs, local paths, or data URIs (one or more strings). data: URIs (data:<mime>;base64,<payload>) work in all server modes; local paths work in stdio mode only. | |
| chat_id | Yes | Target chat: numeric id (e.g. -100…), username without @, or 'me' for Saved Messages. | |
| message | Yes | Message text. When sending files, used as caption. | |
| parse_mode | No | 'markdown'/'html'/'auto': classic entity formatting (auto detects). 'rich': Telegram Rich Message document; dialect auto-detected (known HTML tags outside code → rich HTML, else rich markdown). Default is 'auto'. parse_mode='rich' cannot be combined with files. | auto |
| reply_to_id | No | Telegram message id to reply to. For forums, topic root id; for channel posts, post id (may create a comment). Omit for a new top-level message. |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| chat | No | |
| code | No | |
| date | No | |
| rich | No | |
| text | No | |
| error | No | |
| action | No | |
| params | No | |
| sender | No | |
| status | No | |
| topic_id | No | |
| edit_date | No | |
| exception | No | |
| operation | No | |
| error_code | No | |
| message_id | No | |
| rich_format | No | |
| reply_markup | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (openWorldHint, destructiveHint), so the description carries the burden. It discloses key behavioral details: parse_mode='rich' cannot combine with files, text becomes caption when files are present, channel post reply_to_id auto-posts in discussion group, and precise success/error dict shapes. No contradiction with annotations.
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?
Although longer than two sentences, every sentence carries necessary information. The description is front-loaded with the core action, then layers details logically (format, files, reply, channel behavior, result, alternatives). There is zero fluff; redundant details are delegated to a documentation link.
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?
This is a complex tool with 5 parameters, an output schema, and nontrivial edge cases (parse modes, file handling, reply-to variations, discussion groups). The description covers all of these and also states the success/error return structures, making it complete for selecting and invoking 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 coverage is 100%, giving a baseline of 3, but the description adds significant value: it explains file source types (URLs, local paths, data: URIs), parse_mode dialect detection, reply_to_id semantics for forums/channels, and how 'me' works for chat_id. This goes well beyond the schema's own descriptions.
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 opens with 'Send text and optional file attachments to a Telegram chat' – a specific verb, resource, and scope. It clearly distinguishes send_message from edit_message and send_message_to_phone by naming them and stating their different use cases.
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 explicit when-to-use guidance: '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.' It also covers channel reply behavior and parse_mode rules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | List of attachment URLs, local paths, or data URIs (one or more strings). data: URIs (data:<mime>;base64,<payload>) work in all server modes; local paths work in stdio mode only. | |
| message | Yes | Message text. When sending files, used as caption. | |
| last_name | No | Last name when creating a temporary contact. | Name |
| first_name | No | First name when creating a temporary contact. | Contact |
| parse_mode | No | 'markdown'/'html'/'auto': classic entity formatting (auto detects). 'rich': Telegram Rich Message document; dialect auto-detected (known HTML tags outside code → rich HTML, else rich markdown). Default is 'auto'. parse_mode='rich' cannot be combined with files. | auto |
| phone_number | Yes | E.164 phone number with country code, e.g. +1234567890 (must be on Telegram). | |
| remove_if_new | No | If true, delete the contact after send when it was created only for this send. | |
| reply_to_msg_id | No | Reply to this message id in the target chat after resolve. |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| chat | No | |
| code | No | |
| date | No | |
| rich | No | |
| text | No | |
| error | No | |
| action | No | |
| params | No | |
| sender | No | |
| status | No | |
| topic_id | No | |
| edit_date | No | |
| exception | No | |
| operation | No | |
| error_code | No | |
| message_id | No | |
| rich_format | No | |
| phone_number | No | |
| reply_markup | No | |
| contact_removed | No | |
| contact_was_new | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint, openWorldHint), the description discloses that it may create a temporary contact, can remove it if applicable, and that rich parse mode cannot be combined with files. It also mentions success response fields (contact_was_new/contact_removed), adding significant context.
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 sentences, front-loaded with main purpose, each sentence adds value: primary action, parse_mode constraints, and success result. No fluff or repetition.
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?
With 8 parameters and an output schema, the description covers main behavior, constraints, and success result, plus a link to full docs. It lacks explicit error handling or preconditions (e.g., phone must be on Telegram, though that's in schema). Overall adequate for tool selection.
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 100% with each parameter documented, so baseline is 3. The description adds some context (e.g., rich mode auto-detection, success fields) but does not significantly enhance parameter-level semantics beyond what schema already provides.
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 verb 'Send' and resource 'phone number', and explains the temporary contact creation behavior. This distinguishes it from sibling tools like 'send_message', which likely targets 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?
The description clearly implies when to use this tool: when sending to a phone number. However, it does not explicitly contrast with alternatives like 'send_message', nor does it state exclusions (e.g., use 'send_message' for existing chats). Thus no explicit alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
get_chat_info2 fields changedOutput schema / properties / common_chatsAdded value: +{
+ "items": {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ "type": "array"
+}Output schema / properties / common_chats_has_moreAdded value: +{
+ "type": "boolean"
+}edit_message4 fields changedInput schema / properties / parse_mode / descriptionPrevious value: -"'markdown', 'html', or 'auto' (detect from content). Default is 'auto'."New value: +"'markdown'/'html'/'auto': classic entity formatting (auto detects). 'rich': Telegram Rich Message document; dialect auto-detected (known HTML tags outside code → rich HTML, else rich markdown). Default is 'auto'. parse_mode='rich' cannot be combined with files."Input schema / properties / parse_mode / enumPrevious value: -[
- "markdown",
- "html",
- "auto"
-]New value: +[
+ "markdown",
+ "html",
+ "auto",
+ "rich"
+]Output schema / properties / richAdded value: +{
+ "type": "boolean"
+}Output schema / properties / rich_formatAdded value: +{
+ "type": "string"
+}send_message4 fields changedInput schema / properties / parse_mode / descriptionPrevious value: -"'markdown', 'html', or 'auto' (detect from content). Default is 'auto'."New value: +"'markdown'/'html'/'auto': classic entity formatting (auto detects). 'rich': Telegram Rich Message document; dialect auto-detected (known HTML tags outside code → rich HTML, else rich markdown). Default is 'auto'. parse_mode='rich' cannot be combined with files."Input schema / properties / parse_mode / enumPrevious value: -[
- "markdown",
- "html",
- "auto"
-]New value: +[
+ "markdown",
+ "html",
+ "auto",
+ "rich"
+]Output schema / properties / richAdded value: +{
+ "type": "boolean"
+}Output schema / properties / rich_formatAdded value: +{
+ "type": "string"
+}send_message_to_phone4 fields changedInput schema / properties / parse_mode / descriptionPrevious value: -"'markdown', 'html', or 'auto' (detect from content). Default is 'auto'."New value: +"'markdown'/'html'/'auto': classic entity formatting (auto detects). 'rich': Telegram Rich Message document; dialect auto-detected (known HTML tags outside code → rich HTML, else rich markdown). Default is 'auto'. parse_mode='rich' cannot be combined with files."Input schema / properties / parse_mode / enumPrevious value: -[
- "markdown",
- "html",
- "auto"
-]New value: +[
+ "markdown",
+ "html",
+ "auto",
+ "rich"
+]Output schema / properties / richAdded value: +{
+ "type": "boolean"
+}Output schema / properties / rich_formatAdded value: +{
+ "type": "string"
+}get_messages1 field changedInput schema / properties / from_user / descriptionPrevious value: -"Only return messages from this sender. Accepts: numeric user id, @username, phone (+…), 'me', 'self', t.me URL, -100 prefixed id. Resolved via get_entity_by_id (same as chat_id). Uses Telegram's native from_id server-side filter (per-chat search only)."New value: +"Only return messages from this sender. Not a display-name or contact-name search — bare strings resolve like chat_id via get_entity (usernames are case-insensitive and may match an unrelated channel). Prefer @username, phone (+…), or numeric user id. Also accepts 'me', 'self', t.me URL, -100 prefixed id. Uses Telegram's native from_id server-side filter (per-chat search only)."get_messages3 fields changedInput schema / properties / context / descriptionPrevious value: -"Number of surrounding messages to include as context for each search result. 0 = disabled (default). 1–10 = include N messages before and N after each result. Also fetches the message being replied to and top replies (if include_reply_threads=true). Requires chat_id. Disabled when result count exceeds cost-based caps."New value: +"Number of surrounding messages to include as context for each search result. 0 = disabled (default). 1-10 = include N messages before and N after each result. Also fetches the message being replied to and top replies (if include_replies=true). Requires chat_id. Disabled when result count exceeds cost-based caps."Input schema / properties / include_repliesAdded value: +{
+ "default": false,
+ "description": "If true, fetch up to 5 direct replies per search result and attach as replies. Each result costs one API call (not batchable). Default: false.",
+ "type": "boolean"
+}Input schema / properties / include_reply_threadsRemoved value: -{
- "default": false,
- "description": "If true, fetch up to 5 direct replies per search result and attach as reply_thread. Each result costs one API call (not batchable). Default: false.",
- "type": "boolean"
-}find_chats1 field changedInput schema / properties / query / descriptionPrevious value: -"Name, username (no @), phone (+country…), or comma-separated multi-queries. Required for global search unless you use min_date/max_date or folder alone."New value: +"Name, username (no @), phone (+country…), or comma-separated usernames for batch lookup. Example: 'alice,bob,charlie'. Required for global search unless you use min_date/max_date or folder alone."get_messages3 fields changedInput schema / properties / contextAdded value: +{
+ "default": 0,
+ "description": "Number of surrounding messages to include as context for each search result. 0 = disabled (default). 1–10 = include N messages before and N after each result. Also fetches the message being replied to and top replies (if include_reply_threads=true). Requires chat_id. Disabled when result count exceeds cost-based caps.",
+ "maximum": 10,
+ "minimum": 0,
+ "type": "integer"
+}Input schema / properties / from_userAdded value: +{
+ "default": null,
+ "description": "Only return messages from this sender. Accepts: numeric user id, @username, phone (+…), 'me', 'self', t.me URL, -100 prefixed id. Resolved via get_entity_by_id (same as chat_id). Uses Telegram's native from_id server-side filter (per-chat search only).",
+ "type": "string"
+}Input schema / properties / include_reply_threadsAdded value: +{
+ "default": false,
+ "description": "If true, fetch up to 5 direct replies per search result and attach as reply_thread. Each result costs one API call (not batchable). Default: false.",
+ "type": "boolean"
+}edit_messagefind_chatsget_chat_infoget_messagesinvoke_mtprotosearch_messages_globallysend_messagesend_message_to_phoneClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity – fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge – works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge – works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
