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

secure-telegram-mcp

by antonorlov
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Send prepared media

send_media

Sends media to an in-scope Telegram chat using an opaque handle from prepare_media instead of a filesystem path, with optional caption, forum topic, and idempotency key.

Instructions

Phase 2 of the two-phase media send. Send media to a single in-scope chat using ONLY an opaque handle from prepare_media (no filesystem path is accepted). The target must be inside this endpoint scope; out-of-scope peers, and expired or mismatched handles, are rejected. Subject to the per-endpoint anti-ban quota and, when enabled, human confirmation. An optional idempotency key gives BEST-EFFORT retry de-dup (in-memory, per-process; reset on restart/policy change and NOT covering a send Telegram accepted but reported as failed) — do not assume a retry is safe.

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": {
      "peer": "<peer>",
      "handle": "<handle>"
    },
    "name": "send_media"
  }
}

Input Schema

NameRequiredDescriptionDefault
peerYesChat reference: { kind:'id', value:'<decimal id>' } | { kind:'username', value:'@name' } | { kind:'me' }.
handleYesOpaque handle returned by prepare_media. Pass it back verbatim. It is bound to this session, this endpoint scope, and a short TTL; expired or mismatched handles are rejected. Never pass a filesystem path here.
captionNoOptional media caption, up to 1024 characters.
topicIdNoPost into this forum topic of a forum supergroup (see list_topics).
idempotencyKeyNoOptional caller-supplied idempotency key (url-safe). Reusing it on a retry gives BEST-EFFORT, in-memory de-dup only (not guaranteed across restarts, policy changes, or a send Telegram accepted but reported as failed).

Output Schema

NameRequiredDescriptionDefault
chat_idYesChat the message was sent to.
sent_atYesServer-acknowledged send instant.
message_idYesId of the newly created message.
idempotency_keyYesThe random_id used for idempotent dedup; echoed for traceability.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Beyond the annotations it discloses a per-endpoint anti-ban quota, possible human-confirmation gating, rejection of out-of-scope peers and expired/mismatched handles, and — critically — that the idempotency key is in-memory, per-process, reset on restart, and does not cover a send Telegram accepted but reported as failed. The explicit warning 'do not assume a retry is safe' is exactly the kind of operational caveat an agent cannot get from structured fields.

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 phase relationship and the handle-only rule, then the constraint stack, then the idempotency caveat. It is dense and parenthetical-heavy, and the idempotency sentence runs long, but nearly every clause carries actionable information rather than filler.

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

Completeness5/5

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

An output schema exists so return values need no explanation, and the description still covers the failure modes (out-of-scope peer, expired/mismatched handle, quota, confirmation) plus retry safety. For a two-required-parameter mutation with open-world reach, that is everything an agent needs before calling it.

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% and the schema descriptions already spell out handle binding/TTL, caption limits, topicId and idempotency-key semantics, so the description largely restates them. It adds a little by stressing 'Pass it back verbatim' and 'no filesystem path is accepted' for handle, but that is already in the schema text — baseline 3 applies.

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?

Names the specific verb and resource ('Send media to a single in-scope chat') and anchors it as 'Phase 2 of the two-phase media send' using a handle from prepare_media. That framing lets an agent separate it from prepare_media (phase 1) and from send_message (text) without opening any 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?

It makes the prerequisite explicit (handle must come from prepare_media, no filesystem path accepted) and states the scope constraint on the target. What it does not do is explicitly contrast with siblings like send_message or forward_message, so an agent must infer that media delivery is this tool's lane rather than being told.

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