Telegram MCP — Next Generation

Synchronize Chat History to Local Archive

sync_chat_cache

Read-onlyIdempotent

Pulls new Telegram messages into the local offline cache so you can search chat history without calling the Telegram API. Use before running offline text searches or building message archives.

Instructions

Synchronize remote Telegram chat messages into the local SQLite/FTS5 offline cache database. Use before performing offline text searches or when populating local message archives. To search already synced messages without Telegram API calls, use search_cached_messages. To verify database integrity and index status, use check_cache_health.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`mode`	No	Synchronization mode: 'incremental' (new messages since checkpoint) or 'full' (all messages in batch).	incremental
`limit`	No	Maximum number of items or records to retrieve (integer between 1 and 100).
`account`	No	Optional account label for multi-account environments. If omitted in single-mode, the default account is used. In multi-mode without an account, read-only tools fan out across all configured accounts.
`chat_id`	Yes	Target Telegram chat, group, supergroup, channel, or user identifier. Accepts numeric chat ID (e.g. -1001234567890 or 123456789), username (e.g. '@channel'), or phone number.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv4.1.1Sep 11, 2026

TDQS

A3.8/5.0

Behavior1/5

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

The description states that the tool 'synchronizes ... into the local ... database', which is a write operation, but the annotations include readOnlyHint=true. This is a direct contradiction: readOnlyHint typically means the tool does not modify state. The description also fails to add other behavioral context beyond what annotations already provide, but the contradiction alone forces a score of 1 per the rubric.

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 two sentences with zero fluff. The first sentence states the core purpose, the second provides usage context and alternatives. Information is front-loaded and every word 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?

The description covers purpose, when to use, and alternatives. An output schema exists to describe return values, and annotations cover safety. The only gap is the contradiction with readOnlyHint, which makes the description slightly less reliable but does not leave out necessary call details. For a well-specified tool, this is nearly 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?

Schema coverage is 100%, so the schema fully documents all four parameters. The description adds no parameter-specific meaning beyond what is already in the schema, so the baseline of 3 is appropriate.

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 uses a specific verb ('synchronize'), names the resource ('remote Telegram chat messages') and the target ('local SQLite/FTS5 offline cache database'), and explicitly differentiates from siblings by naming search_cached_messages and check_cache_health. This leaves no ambiguity about what the tool does.

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

Usage Guidelines5/5

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

It gives explicit usage context ('Use before performing offline text searches or when populating local message archives') and names two alternatives with their purposes, effectively telling the agent when not to use this tool. This is textbook usage guidance.

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