Fast MCP Telegram
Server Details
MCP/HTTP Telegram Gateway — Multi-tenant, MTProto User API, 8 tools, multi-user Bearer auth, global search, session ACL, Docker
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.5/5 across 8 of 8 tools scored. Lowest: 3.9/5.
Each tool has a clear, distinct purpose: editing, sending, searching chats, retrieving chat info, reading messages, global search, low-level API, and sending to phone number. There is no ambiguity between tools; they target different actions or scopes.
Tool names follow a verb_noun pattern in snake_case (e.g., edit_message, send_message). Minor inconsistency: 'find_chats' uses 'find' while others use 'get' or 'search', but overall the pattern is predictable.
With 8 tools covering core messaging operations (send, edit, retrieve, search) and a low-level API, the count is well-scoped for a Telegram client MCP server. It is neither too few nor too many.
The set covers essential chat operations (send, edit, read, search, info) and includes invoke_mtproto for unsupported methods. Minor gaps like delete message or manage groups are present, but the low-level tool provides a fallback.
Available Tools
8 toolsedit_messageEdit messageADestructiveIdempotentInspect
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. Success: dict with message_id, date, chat, text, status='edited', and edit_date. 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/leshchenko1979/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', or 'auto' (detect from content). Default is 'auto'. | auto |
Output Schema
| Name | Required | Description |
|---|---|---|
| ok | No | |
| chat | No | |
| code | No | |
| date | 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 | |
| reply_markup | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (idempotent, destructive, open world), the description adds critical context: only editable by the sender, only text, success/error response format, and return fields. 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?
Every sentence adds value: purpose, constraints, return format, usage guidance, and doc link. No fluff, well structured with most critical info first.
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 input schema coverage, annotations, and output schema, the description is complete: covers what, constraints, errors, usage, and links to full docs. No missing context.
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%, baseline 3. The description adds value by explaining parse_mode detect behavior and clarifying message_id source ('from get_messages or Telegram'). Slight improvement over 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 states the tool replaces text of an existing message, with specific constraints (only own messages, text only). It distinguishes from siblings like send_message.
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?
Explicitly says when to use: 'Use edit_message to update a previously sent message; use send_message to create new ones.' Also mentions it only works on messages sent by the authenticated account, guiding appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
find_chatsFind chatsARead-onlyIdempotentInspect
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/leshchenko1979/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. |
Output Schema
| Name | Required | Description |
|---|---|---|
| ok | No | |
| code | No | |
| chats | No | |
| error | No | |
| action | No | |
| params | No | |
| exception | No | |
| operation | No | |
| error_code | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, openWorldHint, and idempotentHint. The description adds detailed behavioral context: parallel search for comma-separated usernames, round-robin merging, and different filtering behaviors depending on parameters. No contradictions.
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 relatively long but well-structured, with key information front-loaded. The second sentence is dense but necessary to explain multiple search modes. Could be slightly more concise, but no wasted words.
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 7 parameters with 100% schema coverage, existing output schema, and rich annotations, the description covers all aspects: search modes, parameter interactions, return format, and a link to full documentation. No gaps.
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%, so baseline is 3. The description adds value by explaining parameter interplay (e.g., query requirement for global search) and clarifying the folder parameter's internal distinction. This goes beyond the schema's per-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 specifies the action ('Find') and the resources ('users/groups/channels'), with multiple search modes explained. It distinguishes itself from sibling 'search_messages_globally' by focusing on chats rather than messages.
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 guidelines on when to use different search modes (global vs dialog list vs folder), including required conditions for global search. However, it does not explicitly state when not to use this tool or compare to other siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_chat_infoGet chat infoARead-onlyIdempotentInspect
Load profile and metadata for one user, bot, group, or channel. Success: info dict; forum chats may include topics up to topics_limit. Full documentation: https://github.com/leshchenko1979/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. |
Output Schema
| 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 | |
| topics_has_more | No | |
| participants_count | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, openWorldHint. Description adds that forum chats may include topics up to topics_limit, which is useful but not extensive. No contradictions.
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 concise sentences: core purpose, success behavior with forum note, and link to full docs. No wasted words, front-loaded.
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?
Output schema exists, so return values need not be detailed. Description covers success outcome and a key parameter effect. Slightly missing error handling or preconditions, but adequate.
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%, baseline 3. Description adds context to topics_limit by explaining its role in forum chats, and chat_id is well-described 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?
Description explicitly states 'Load profile and metadata for one user, bot, group, or channel.', using a specific verb and resource, and clearly differentiates from siblings like get_messages or find_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?
Implicitly suggests use for a single chat, but no explicit when-to-use, when-not-to-use, or alternatives provided. Lacks guidance on when to prefer find_chats or search_messages_globally.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_messagesGet messages in chatARead-onlyIdempotentInspect
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/leshchenko1979/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. 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). | |
| 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). |
Output Schema
| 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 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant context beyond the annotations (readOnlyHint, idempotentHint, openWorldHint), detailing response structure (messages, has_more, optional total_count and discussion fields), mode behavior, and server-side filtering. No contradictions 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?
The description is front-loaded with the core capabilities and then provides detailed guidance without redundancy. Every sentence adds value, and the structure logically progresses from purpose to usage to constraints.
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 (13 parameters, multiple modes, output schema), the description is remarkably complete: it covers all modes, parameter interactions, edge cases (e.g., context disabled when caps), and references full documentation. The output schema's existence reduces the burden to describe return values, but the description still covers the key response fields.
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, the description adds meaningful extra context: mutual exclusivity rules, explanation of context and include_replies behavior, and clarification of from_user resolution. This goes well beyond the schema 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's purpose: 'Read or search messages in one chat: browse latest, search text, fetch by ids, or load replies to a message.' It specifies the resource (messages in one chat) and verbs, and implicitly differentiates from sibling search_messages_globally by scoping to a single chat.
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 usage guidance, including modes (browse, search, fetch by IDs, replies), parameter combinations to avoid ('Do not combine message_ids with query or reply_to_id'), and constraints like context disabled when caps exceeded. It also references full documentation for more details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
invoke_mtprotoInvoke MTProtoADestructiveInspect
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/leshchenko1979/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). |
Output Schema
| 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 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint and openWorldHint. The description adds that dangerous methods require allow_dangerous=true and mentions the return format (API result dict or normalized error), which goes beyond 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?
Two sentences, front-loaded with purpose, then usage, then result. Every sentence is informative without 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?
The description covers purpose, usage, safety, and result format. With output schema present, it doesn't need to detail return structure. Could mention potential errors more explicitly, but the mention of 'normalized error' suffices.
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 adds minimal extra meaning beyond the schema, only reiterating the allow_dangerous flag concept.
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 it is a low-level Telegram API (MTProto) invoke for methods not wrapped by other tools, which distinguishes it from sibling tools that wrap specific endpoints.
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 'for methods not wrapped by other tools', indicating when to use. It also warns about dangerous methods requiring allow_dangerous=true. However, it doesn't explicitly list when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_messages_globallySearch messages globallyARead-onlyIdempotentInspect
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/leshchenko1979/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). |
Output Schema
| 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 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: it notes that global search ignores include_total_count, which is not captured by readOnlyHint or idempotentHint. It also mentions optional filters. No contradictions 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?
The description is two sentences plus a link, front-loaded with the key purpose. Every sentence adds value, no fluff. Efficient 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 8 parameters and an output schema, the description covers the main purpose, key filters, and a behavioral note. It could mention default limit and auto_expand_batches, but with output schema present and link to full docs, it is sufficiently complete. Minor gap in fully explaining all parameters.
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%, so baseline is 3. The description adds value by explaining query terms are comma-separated and OR-style, and clarifies that public filter does not apply to private DMs. It also mentions that global search ignores include_total_count, which is a behavioral nuance not in schema descriptions. Adds meaningful context beyond 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 states the tool searches all Telegram chats at once, distinguishing it from siblings like get_messages which are scoped to one chat. The verb 'search' and resource 'messages globally' 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?
The description explains comma-separated query terms and optional filters, and notes that global search ignores include_total_count. While it doesn't explicitly state when to use this tool versus alternatives (e.g., get_messages for single chat), the global scope is clearly indicated, and a link to full documentation is provided. Slight omission of explicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
send_messageSend messageADestructiveInspect
Send text and optional file attachments to a Telegram chat. Supports reply-to (including forum topics and channel discussion groups), auto-detected or explicit parse_mode (markdown/html), and 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. 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/leshchenko1979/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', or 'auto' (detect from content). Default is 'auto'. | 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. |
Output Schema
| Name | Required | Description |
|---|---|---|
| ok | No | |
| chat | No | |
| code | No | |
| date | 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 | |
| reply_markup | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint: true, but the description adds context: files turn text into caption, reply_to_id behavior for forums/channels, and the success/error return format. It does not contradict 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?
The description is front-loaded with the main action, then details. Each sentence adds value, no fluff. It references full documentation externally, keeping the inline description compact.
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 input schema fully describes all parameters and the output schema is described (success/error dicts), the description is complete. It covers the tool's behavior, limitations, and usage context.
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?
All 5 parameters have descriptions in the schema (100% coverage). The description adds behavioral meaning: reply_to_id supports forum topics and discussion groups, parse_mode can be auto-detected, files support various URL types. This goes beyond the schema details.
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 'Send text and optional file attachments to a Telegram chat', specifying verb ('send'), resource ('message to Telegram chat'), and scope. It explicitly distinguishes from siblings by naming edit_message and send_message_to_phone.
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 explains the automatic behavior for channel posts with reply_to_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
send_message_to_phoneSend message to phoneADestructiveInspect
Send to a phone number: may create a temporary contact, then send text or files. Success: send result plus contact_was_new / contact_removed when applicable. Full documentation: https://github.com/leshchenko1979/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', or 'auto' (detect from content). Default is 'auto'. | 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. |
Output Schema
| Name | Required | Description |
|---|---|---|
| ok | No | |
| chat | No | |
| code | No | |
| date | 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 | |
| phone_number | No | |
| reply_markup | No | |
| contact_removed | No | |
| contact_was_new | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: it may create a temporary contact, and the success response includes fields like contact_was_new and contact_removed. Annotations already flagged destructive hint, so the description provides useful elaboration without contradiction.
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 and a link, front-loading the core action. It is concise without wasted words, though a bit more detail on side effects could fit.
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 an output schema and 100% schema coverage, the description sufficiently covers the tool's behavior, mentioning return values and linking to full docs for completeness. It adequately addresses the 8-parameter 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?
Schema coverage is 100% with descriptions, so baseline is 3. The description does not add meaning beyond what the schema already provides for parameters like phone_number, message, or remove_if_new.
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 sends a message to a phone number, potentially creating a temporary contact. It distinguishes from siblings like 'send_message' which targets chat IDs, and other tools like 'edit_message' or 'get_messages' that serve different purposes.
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 use when sending to a phone number, but does not explicitly state when not to use it or provide comparisons to alternatives like 'send_message'. It lacks guidance on prerequisites such as requiring the number to be on Telegram.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
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
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.
Discussions
No comments yet. Be the first to start the discussion!