Skip to main content
Glama
stufently

telegram-ai-cli-mcp

by stufently
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

telegram_search

Read-onlyIdempotent

Search Telegram messages by words in one chat or across your account, with optional context and read-policy filtering.

Instructions

Scoped to a chat, the read policy is checked once for that chat, and context may bring back the messages either side of each match, marked match: false. Use when the user asks to find messages by words, in one chat or across the account. Do not use this for a regular expression or for text already copied locally; call telegram_archive_search for that, or telegram_chat_read to page the latest history. Unscoped, every result is checked against the policy for its own chat and the number withheld is reported.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
chatNoRestrict to one chat. Omit to search everything this account can see.
limitNoMatching messages to return. `context` adds rows on top of this, so `meta.returned` can exceed it; `meta.matches` is what this caps.
queryYesText to look for.
accountNoAccount label to use. Omit when exactly one account is configured.
contextNoMessages to include either side of each match, marked `match: false` so they are not counted as hits. Single-chat searches only; the first 10 matches get context and a warning names the rest. 0, the default, returns matches alone.
before_idNoOnly messages older than this id (single-chat searches only).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare read-only/idempotent/no-destruction, but the description adds genuine behavioral context beyond them: per-chat read-policy checking, the withheld-count reporting when unscoped, and the `match: false` marking of context rows. Return format and pagination are not covered, keeping it short of a 5.

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?

Four sentences, each carrying routing or policy information with little waste. It leads with scoped-read-policy behavior rather than the core action, which slightly weakens front-loading, but nothing is filler.

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?

With 100% schema coverage, annotations covering the safety profile, and no output schema, the description supplies what structured fields cannot: policy-check behavior and sibling disambiguation. It is complete enough to call correctly, missing only return-shape/pagination notes.

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 all six parameters are already documented and the baseline is 3. The description reinforces `context` semantics (match:false, single-chat) but adds little that the schema descriptions do not already provide.

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?

States a specific verb+resource (find messages by words) and explicitly frames scope as one chat or account-wide. It names the sibling tools it is not (telegram_archive_search, telegram_chat_read), so an agent can distinguish it without opening a schema.

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?

Explicit when-to-use ('user asks to find messages by words'), explicit when-not (regex, text already copied locally), and names the correct alternatives for each case. Routing is unambiguous.

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