Skip to main content
Glama
egor-fedorov

Telegram Context MCP

by egor-fedorov
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

get_history

Read-only

Read Telegram chat history by date range or fetch recent messages across chats, folders, and forum topics, with cursor-based pagination for complete results.

Instructions

Read history over [date_from, date_to), or a chat's recent messages if dates are omitted.

    Supply exactly one of chat_id, chat_ref (numeric ID, @username, or t.me[/s]/username),
    chat_ids or folder_ids. chat_ids/folder_ids read several permitted sources in one
    traversal and require both dates. They default to ordering=page (early results,
    sorted within each page), max_sources=20 and max_messages=100; a larger selection
    returns SOURCE_LIMIT_EXCEEDED before reading. budget reports emitted messages;
    exhausted=true keeps next_cursor, and only an explicitly larger max_messages
    continues it. ordering=global waits for every source to keep strict order.
    Omit topic_id for chat-wide history, or supply a positive forum topic ID (General is 1)
    with a single chat. Topics require ordinary access to a supported forum supergroup.
    Follow next_cursor for a complete period, repeating the original arguments.
    Public channels outside the allowlist require allow_public_channel_reads and an
    explicit chat selector. Temporary failures retain next_cursor; respect
    retry_after_seconds before continuing.

Input Schema

NameRequiredDescriptionDefault
limitNo
orderNonewest_first
cursorNo
chat_idNo
date_toNo
chat_idsNo
chat_refNo
orderingNo
topic_idNo
date_fromNo
folder_idsNo
max_sourcesNo
max_messagesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.6.0

TDQS

A4.1/5.0
Behavior5/5

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

Beyond readOnlyHint and openWorldHint, the description discloses many behavioral details: half-open date range, default ordering/max_sources/max_messages, SOURCE_LIMIT_EXCEEDED before reading, budget/exhausted cursor semantics, ordering=global synchronization, forum access requirements, allowlist requirements, and retry_after_seconds handling. These are substantial operational disclosures not present in 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 front-loaded with the core operation and then organized around selector rules, pagination, topics, and access constraints. It is dense but mostly earns its length given the 13-parameter complexity, though some sentences are run-on and could be tighter.

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?

For a read-only history tool with no output schema, the description covers the critical invocation behaviors: selector exclusivity, date requirements, pagination, limits, error conditions, topic access, and public-channel access. Remaining gaps around limit/order semantics and full return-shape expectations keep it from being complete.

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?

With 0% schema description coverage across 13 parameters, the description must compensate. It explains most important selectors and controls (chat_id/chat_ref/chat_ids/folder_ids, dates, ordering, topic_id, max_sources, max_messages, cursor follow-up), but it omits limit and order entirely and uses 'next_cursor' while the schema parameter is 'cursor'.

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?

The first sentence states a specific verb and resource: read history over a date range, or recent chat messages when dates are omitted. It clearly describes the tool's scope, but it does not explicitly differentiate it from sibling tools such as search_messages or get_messages.

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 gives detailed usage constraints: supply exactly one chat selector, multi-source reads require both dates, topic_id is only for a single chat, and public channels need allow_public_channel_reads. It does not explicitly name when to prefer this tool over sibling search or message-retrieval tools, leaving that to inference.

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