Static source inference · medium confidence · detected: Sampling
Deprecated protocol patterns detected
Summary
The Telegram MCP server has well-structured tool definitions with proper names and schemas, but critical gaps in parameter descriptions and output schema documentation significantly limit its quality. Tool names follow verb_noun conventions (send_message, get_channel_info, forward_message, pin_message, get_channel_members), which is correct. However, many parameters lack meaningful descriptions beyond their type, and no tool documents its return schema or what fields the LLM should expect. The descriptions are adequate but generic. Error handling is not visible in the tool definitions. Most critically, there is no evidence of output schema documentation, which prevents LLMs from planning downstream operations or understanding what data they receive.
No documented output schemas for any tool. LLMs cannot plan downstream operations or understand what fields to extract from responses (e.g., GET_CHANNEL_INFO returns what fields? GET_CHANNEL_MEMBERS returns what structure?). This violates the foundational pattern that tools must declare what they return.
Parameter descriptions lack actionable detail. For example, GET_CHANNEL_INFO 'channelId' description is 'The channel ID or username (e.g., @channelname or -1001234567890)', this includes example values which LLMs may reuse literally. GET_CHANNEL_MEMBERS 'limit' lacks context on what happens when limit is exceeded or when there are fewer members than requested.
GET_CHANNEL_MEMBERS uses 'limit' with min/max but provides no documentation about pagination behavior or what 'next_cursor' should be returned. The tool is pageable but doesn't expose pagination metadata in the schema.
Recommendations
Document the return schema for every tool. For GET_CHANNEL_INFO, specify: 'Returns {id, title, type, members_count, description, ...}'. For GET_CHANNEL_MEMBERS, specify: 'Returns {members: [{id, first_name, last_name, username, is_bot}], total_count, next_offset}'. This is required for LLMs to plan multi-step operations.
Remove example IDs from descriptions. Replace '(e.g., @channelname or -1001234567890)' with a constraint like 'Format: string starting with @ for username, or negative number for channel ID'. Use the schema type union to enforce this, not examples.
Add recovery guidance to parameter descriptions. For chatId: 'If you have only the channel name, use GET_CHANNEL_INFO first to resolve it to a numeric ID.' For FORWARD_MESSAGE's messageId: 'If you lack the message ID, call GET_CHANNEL_MESSAGES with a search query.'
For GET_CHANNEL_MEMBERS, add pagination metadata to the response schema: 'Returns {members: [...], total_count, has_more: boolean, next_offset: number}'. Document whether the tool returns only administrators or all members.
Expand tool descriptions from their current ~50-80 chars to 100-200 chars. For example, GET_CHANNEL_INFO: 'Retrieve channel metadata including title, member count, description, and type (private, public, supergroup). Required before sending messages to channels you have only a username for.'
Add explicit error handling guidance. For SEND_MESSAGE: 'Returns error 'chat_not_found' if the channel does not exist, verify the chatId format. Returns 'user_not_a_member' if the bot is not in the channel, add the bot first.'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Sampling (deprecated) - integrate directly with the LLM provider API
No error handling documentation in any tool. What happens if chatId is invalid? If a message cannot be pinned? If a user lacks permission? Tools must guide LLMs on recovery actions (e.g., 'If user not found, try search_users() first').
Overloaded 'chatId'/'channelId' parameters accept both string (username like @channelname) and number (numeric ID like -1001234567890) but lack guidance on when to use which. This type union is ambiguous, the description should clarify the priority and conversion rules.
SEND_MESSAGE includes example values 'Markdown', 'MarkdownV2', 'HTML', 'Text' as enum but the description also mentions 'Use Text for plain text without formatting', which is redundant once enums are declared. LLMs will latch onto the enum description text.
SEND_MESSAGE
Clarify when topicId (SEND_MESSAGE) and disableNotification (PIN_MESSAGE, FORWARD_MESSAGE) are appropriate. Add dependency hints: 'topicId: Only required for forum channels (type: 'forum'). Omit for regular channels.'
Document the SEND_MESSAGE response structure explicitly: 'Returns {message_id, date_sent, text, chat_id}. Use message_id in subsequent PIN_MESSAGE or FORWARD_MESSAGE calls.'
For GET_CHANNEL_MEMBERS, add constraint documentation: 'limit must be 1 - 50; defaults to 10. Returns up to limit members; if more exist, include next_offset in response for pagination.'
Add idempotency guidance where applicable. PIN_MESSAGE: 'Pinning an already-pinned message is idempotent, returns success without error.' SEND_MESSAGE: 'Sending identical messages twice may result in duplicate messages, no deduplication.'
Separate 'channelId' and 'chatId' naming if they have different meanings. Currently used interchangeably but this is ambiguous. Pick one and use consistently.