Skip to main content
Glama
prabchevski

Telegram Search MCP

by prabchevski

List recent Telegram voice messages

telegram_list_voice_messages
Read-onlyIdempotent

List voice and video notes from a specified Telegram chat, ordered newest first, with optional pagination via before_message_id.

Instructions

List voice notes and video notes in one known cloud chat, newest first.

Use next_before_message_id for older pages. No speech recognition is started.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNo
chat_idYes
before_message_idNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
itemsYes
trust_boundaryNo
next_before_message_idYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.8.0

TDQS

A4/5.0
Behavior4/5

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds value by disclosing ordering, restricting the result to voice/video notes, scoping to a known cloud chat, and explicitly stating that no speech recognition is started. No contradictions with 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?

Three short sentences, front-loaded with the core purpose, and no filler. The pagination sentence is useful but uses 'next_before_message_id' rather than the schema's 'before_message_id', which slightly reduces precision.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a list tool with output schema and read-only annotations, it covers scope, ordering, media types, and pagination. The main gap is the cursor name ambiguity: an agent may look for 'next_before_message_id' as an input field because the schema only exposes 'before_message_id'. This is a small but real obstacle to correct invocation.

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 description coverage is 0%, so the description must compensate. It partially does: 'one known cloud chat' clarifies chat_id and 'Use next_before_message_id for older pages' indicates pagination behavior. However, it never names the input parameter before_message_id, leaving the exact mapping of the cursor to the schema ambiguous, and limit is left entirely to the schema.

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 states a specific verb and resource: lists voice notes and video notes in a single known cloud chat, ordered newest first. This clearly separates it from sibling tools like telegram_get_chat_history (all messages) and telegram_transcribe_voice (audio transcription).

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 clear operating context: one known chat, voice/video notes only, newest-first ordering, and a pagination instruction for older pages. It does not explicitly name alternatives or say when not to use it, but the 'No speech recognition' line and media-type focus make the intended use apparent.

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