Telegram MCP

Overview Schema Source Related Servers Discussions Admin

Read an exact Telegram message pin state

telegram_get_pin_info

Read-onlyIdempotent

Check whether a specific Telegram message is pinned or retrieve the newest pinned message for a chat, using native message IDs without modifying the chat.

Instructions

Read exact native message IDs and pin state without changing Telegram.

With message_id, checks that exact message. Without it, returns only the newest pinned message, or null if Telegram reports none. This is not a complete pin list and does not identify who pinned a message. To list pins, paginate search_chat_messages with media_type=pinned. Never convert IDs.

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": {
      "chat_id": "<chat_id>"
    },
    "name": "telegram_get_pin_info"
  }
}

Input Schema

Name	Required	Description	Default
`chat_id`	Yes
`message_id`	No

Output Schema

Name	Required	Description	Default
`scope`	Yes
`chat_id`	Yes
`is_pinned`	Yes
`message_id`	Yes
`can_be_pinned`	Yes
`trust_boundary`	No

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.12.0Nov 4, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered; the description adds genuinely new context: the null result when Telegram reports no pin, the 'newest only' truncation, and the absence of pinner identity. It does not discuss auth scope or rate limits, keeping it just below the top mark.

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?

Short, front-loaded, and organized as scope statement, then parameter behavior, then limitations, then alternative. Every sentence contributes, though 'Never convert IDs' is terse to the point of being cryptic about which ID formats are expected.

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?

An output schema exists so return values are not the description's job; it still correctly documents the null case and the non-completeness caveat. The remaining gap is chat_id semantics for a tool whose whole purpose is targeting a specific chat and message pair.

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 carries the burden. It explains message_id's dual behavior well and warns 'Never convert IDs', but chat_id — the only required parameter — is never described in terms of format or accepted values, leaving half the parameters uninterpreted.

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 and resource ('Read exact native message IDs and pin state') and immediately scopes it away from siblings by noting it is not a complete pin list and does not identify the pinner. An agent can distinguish this from telegram_get_pin_status and telegram_search_chat_messages without opening either 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?

Gives explicit branching behavior: with message_id it checks that exact message, without it returns only the newest pinned message or null. It also names the alternative ('paginate search_chat_messages with media_type=pinned') for the listing use case, so both when-to-use and when-to-use-something-else are covered.

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

Deploy Server