fast-mcp-telegram

by io.github.leshchenko1979

Get messages in chat

get_messages

Read-onlyIdempotent

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

Input Schema

TableJSON Schema

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).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`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

TDQS

A4.5/5.0

Behavior5/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, and the description aligns with these. Beyond that, it discloses meaningful behavioral details: include_replies costs an API call per result, context is disabled when cost caps are exceeded, and the response contains messages, has_more, and optional total_count/discussion fields. This goes well beyond the structured annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a compact, front-loaded paragraph covering purpose, key parameters, a constraint, and response fields, followed by a documentation link. Every sentence contributes value; no filler or redundancy. It is appropriately sized for a tool with 13 parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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, output schema present), the description provides a complete high-level picture: usage modes, key parameter roles, mutual exclusions, cost behavior, and response shape. The link to full documentation covers any remaining edge cases. The output schema handles return value details, so the description need not repeat them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 groups parameters into usage modes and highlights constraints (e.g., not combining message_ids with query/reply_to_id), but most of this information already appears in the parameter descriptions within the schema. No significant new semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states "Read or search messages in one chat" and enumerates specific modes: browse latest, search text, fetch by ids, load replies. This distinguishes it from siblings like search_messages_globally (global search) and send_message (send). The verb+resource+scope is specific and immediately understandable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on how to use the tool: use from_user for sender filtering, context for neighboring messages, include_replies for direct replies, and explicitly warns "Do not combine message_ids with query or reply_to_id." It implies per-chat scope but does not explicitly name sibling alternatives like search_messages_globally, so it stops short of a perfect 5.

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

All fast-mcp-telegram tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.3/5.0

Disambiguation5/5

Each tool serves a distinct purpose: sending vs editing messages, per-chat vs global search, finding vs retrieving chat info, and a low-level API escape hatch. No two tools overlap in functionality.

Naming Consistency4/5

Tool names follow a consistent verb_noun pattern in snake_case (e.g., send_message, get_chat_info). Minor deviation with 'search_messages_globally' (adverb inserted) and 'invoke_mtproto' (different verb), but overall pattern is clear.

Tool Count5/5

8 tools is a well-scoped set for a Telegram assistant. It covers core operations without being overwhelming or too sparse.

Completeness3/5

Covers send, edit, read, search, and chat discovery. Missing delete and forward message tools, but the low-level invoke_mtproto can compensate. Notable gaps in common messaging workflows.

Get messages in chat

Input Schema

Output Schema

TDQS

Glama MCP Gateway

TDQS

Resources