Skip to main content
Glama
egor-fedorov

Telegram Context MCP

by egor-fedorov
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

search_messages

Read-only

Search permitted Telegram chats by keyword and narrow results by date, chat, sender, content type, or links, using cursors for ordered paging.

Instructions

Search permitted chats with early results, sorted within each page by default.

    ordering=page visits sources fairly without waiting for every source. Ordering
    between pages is not guaranteed. Use ordering=global for a strictly ordered
    traversal, which can require empty preparation pages. The response reports the
    actual ordering guarantee. order chooses newest_first or oldest_first. Repeat
    both parameters with a cursor. Restricted searches only fetch permitted chats.

    Dates include a timezone; interval is [date_from, date_to). Folder IDs form a union;
    explicit chat_ids intersect that union. Omitted selectors use all permitted dialogs.
    has_link=true selects URL-bearing posts, independently of content_type; only then
    may query be empty. has_link=false excludes links. Omit it for either kind.
    Uses Telegram keyword search, not semantic search. Native sender search and local
    date/content filtering are combined. Partial/empty pages may carry next_cursor.
    Configured public-channel access applies only to explicit chat_ids, never implicit scope.
    Temporary failures retain next_cursor; respect retry_after_seconds before continuing.

Input Schema

NameRequiredDescriptionDefault
limitNo
orderNonewest_first
queryYes
cursorNo
date_toNo
chat_idsNo
has_linkNo
orderingNopage
date_fromNo
sender_idNo
folder_idsNo
content_typeNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.6.0

TDQS

A4.2/5.0
Behavior5/5

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

Adds rich behavioral context beyond the readOnlyHint and openWorldHint annotations: page-vs-global ordering guarantees, cursor reuse requirements, partial/empty pages, retry_after_seconds on temporary failures, and restricted-access behavior. Nothing contradicts the annotations, and the extra detail materially helps an agent invoke it correctly.

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 dense but appropriately sized for a 12-parameter search tool, and it front-loads the core purpose. Some sentences could be organized more scannably, but most content is relevant and earns its place.

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?

Given the complex search behavior, low schema description coverage, and no output schema, the definition is largely complete: it covers ordering, pagination, filtering, access scope, and retry behavior. It could be stronger with explicit limit semantics and a brief sense of the response shape.

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

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates well by explaining ordering, order, cursor, date_from/date_to semantics, folder_ids union behavior, chat_ids intersection, has_link constraints, and query emptiness rules. It still omits limit semantics and does not fully enumerate content_type behavior, leaving some gaps across 12 parameters.

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

Purpose4/5

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

States a specific verb and resource ("Search permitted chats") and clarifies the search mode (Telegram keyword, not semantic), which helps distinguish it from semantic or public-channel search siblings. It does not explicitly name alternative tools or say when to prefer them, so it is clear but lacks direct sibling differentiation.

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?

Provides substantial usage guidance: when to use ordering=page vs. global, how order and cursor interact, how date intervals work, how folder_ids and chat_ids combine, and when has_link allows an empty query. It lacks explicit guidance on when to use this tool instead of get_messages, get_history, or search_public_channels.

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

Deploy Server

Other Tools