Skip to main content
Glama
Sign In
secure-telegram-mcp

secure-telegram-mcp

by antonorlov
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Search messages (in-scope)

search_messages
Read-only

Find messages only within authorized in-scope Telegram peers; omit peer to search across the scope, or specify one peer and topic to narrow results. Never performs global searches.

Instructions

Search messages within this endpoint’s in-scope peers only. Omit peer to fan out across the whole scope (each peer read-gated), or set it to search one in-scope peer. Add topicId (with peer) to search a single forum topic. Never performs a global search. Telegram-originated strings are returned as structured JSON under named keys (untrusted_text, sender_display_name), never as prose.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "search_messages"
  }
}

Input Schema

NameRequiredDescriptionDefault
peerNoOptional single in-scope peer to search; omit to fan out across the whole scope.
limitNoPage size, clamped to [1, 100] (default 20).
queryYesFull-text query, 1..256 chars; matched ONLY within in-scope peers (never a global search).
cursorNoOpaque composite cursor from a prior search page; pass verbatim.
topicIdNoRestrict the search to one forum topic; requires `peer` (a topic exists inside a single forum supergroup).

Output Schema

NameRequiredDescriptionDefault
countYesNumber of messages in this page.
messagesYesThe matching in-scope messages for this page.
truncatedNoTrue when the page was cut to fit the output byte cap; re-query with a smaller limit.
next_cursorNoOpaque composite cursor for the next page; pass back verbatim.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already cover safety (readOnlyHint=true, destructiveHint=false, idempotentHint=false), and the description adds real context beyond them: each peer read is gated, global search never happens, and Telegram-originated strings come back as structured keys (untrusted_text, sender_display_name) rather than prose — a meaningful untrusted-content signal. It stops short of describing ordering, relevance, or result-count behavior.

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?

Front-loaded with the scope rule, then parameter behaviors, then the untrusted-content caveat — each sentence carries a distinct rule. Slightly repetitive with 'in-scope' and 'never a global search' appearing in both prose and schema, but no wasted sentences.

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 5-param, read-only search with a full schema and an output schema, the description covers scope, fan-out, topic restriction, and return-shape caveats. Minor omissions (pagination flow via `cursor`, ordering) are adequately handled by the schema's own parameter descriptions.

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?

Schema coverage is 100%, so baseline is 3; the description goes further by explaining the cross-parameter relationship (topicId only meaningful alongside peer, since a topic lives inside one forum supergroup) and the fan-out semantics of omitting peer. That adds meaning the schema alone only states as a constraint.

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 (search messages) plus a hard scope qualifier ('within this endpoint's in-scope peers only') and explicitly negates the global-search interpretation. An agent can immediately separate this from get_messages or any broad search, without opening the schema.

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?

Gives concrete routing rules: omit `peer` to fan out, set `peer` to target one peer, add `topicId` with `peer` for a single forum topic. It does not contrast itself with the sibling get_messages/get_pinned_messages, so the 'search vs. fetch' decision is left implicit.

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

This server cannot be deployed

Other Tools