Skip to main content
Glama

fast-mcp-telegram

by io.github.leshchenko1979

Find chats

find_chats
Read-onlyIdempotent

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

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum chats to return (recommended 50 or less).
queryNoName, 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.
folderNoTelegram 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.
publicNoIf true, prefer chats with a public username; if false, without. Does not apply to private DMs. Omit to skip this filter.
max_dateNoInclusive maximum date filter (ISO 8601 date or datetime). Omit for no upper bound.
min_dateNoInclusive minimum date filter (ISO 8601 date or datetime). Omit for no lower bound.
chat_typeNoComma-separated chat kinds: private, bot, group, channel. Case-insensitive; extra spaces allowed.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
okNo
codeNo
chatsNo
errorNo
actionNo
paramsNo
exceptionNo
operationNo
error_codeNo

TDQS

A4.3/5.0
Behavior5/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the agent knows this is a safe read. The description adds behavioral details like round-robin merging, global vs dialog-list search behavior, and the success dict shape, which go beyond the annotations.

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

Conciseness4/5

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

The description is three sentences, but the middle sentence is a long, dense enumeration of search modes and filter behaviors. Purpose is front-loaded, but the length and complexity reduce readability slightly.

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

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main search modes, result merging, and the success return shape, and an output schema exists. It references full documentation for more, which is acceptable. However, the mention of 'filter', 'include_peers', and 'flag-based filters' not present in the schema could confuse an agent trying to invoke the tool.

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?

All 7 parameters have schema descriptions (100% coverage), so baseline is 3. The overall description adds context about how query interacts with date filters, but the schema already documents each parameter's purpose and defaults. No major additional semantics beyond what's in 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 opens with 'Find users/groups/channels by name, username, or phone', which is a specific verb and resource. It clearly distinguishes itself from siblings like search_messages_globally by focusing on chat discovery rather than message content search.

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 explains when global search applies (query required) versus dialog list-based search with date filters, and notes that comma-separated usernames are processed in parallel. However, it doesn't explicitly state when to prefer this over alternatives like get_chat_info, and no 'when not to use' guidance is given.

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

Resources