Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
mcp-telegram demonstrates solid foundational work with verb-leading tool names, structured input schemas, and HTTP transport. However, it suffers from inconsistent parameter descriptions, missing output schema documentation, and weak error handling guidance. Most tools fall into the 'fair' category (60-69) due to present-but-incomplete documentation. The server shows engineering rigor (strong build infrastructure, type checking with mypy, comprehensive testing), but does not translate this into LLM-optimized tool definitions. Tool descriptions are functional but generic, they explain what the tool does but not when to prefer it over similar tools or what the agent should do with results. Parameters vary widely in clarity: some have detailed descriptions with constraints; others are sparse. Output schemas are not documented for any tool, forcing LLMs to guess result structure and risking mid-chain failures.
Tools (12)
get_entity_inforead only50/100
Get profile information for a user, bot, group, supergroup, or channel
get_inboxread only50/100
Get personal body-rich unread notifications from inbox
get_sync_statusread onlysource verified63/100
Get the synchronization status of local Telegram history coverage
get_unread_summaryread only50/100
Get compact unread overview from persisted dialog facts
Parameter descriptions are inconsistent in depth and guidance. Some are terse ('Dialog ID of the forum') with no constraint hints; others mention enums but lack guidance on when to use each value. LLMs cannot reliably disambiguate or validate inputs.
Document return schemas for all tools. Use JSON Schema (with type, description, examples for non-sensitive fields). E.g., 'search_messages returns {type: array, items: {type: object, properties: {message_id: integer, text: string, sender_id: integer, timestamp: string}}}'. Post this in tool descriptions or a separate schema reference.
Enrich parameter descriptions with format hints and constraints. Replace generic 'Dialog ID' with 'Telegram dialog ID (integer, typically 10+ digits representing chat or channel). Use list_dialogs to discover available dialog_ids if only channel/group names known.' For enum params, add context: 'navigation: how to browse message history. Use "latest" to read newest messages first (default), "start" to read from oldest.'
Add 'when to use' and 'not to use' guidance to tool descriptions. E.g., 'search_messages: for full-text search across all dialogs or within a specific dialog. Slower than list_messages but finds messages by content. Use list_messages if you know the dialog and want sequential browsing by date/ID.'
Document error handling and recovery paths. Add to each tool description: 'On invalid dialog_id, returns error. Verify with list_dialogs first. Retries are safe (idempotent, no side effects).' For search_messages: 'If no results, try broader query or check if dialog is enrolled in sync via get_sync_status and mark_dialog_for_sync.'
Accept human-readable identifiers (channel names, group names, usernames) alongside IDs. For list_messages, search_messages, and list_topics, add optional 'dialog_name' or 'channel_name' parameters that internally resolve to exact_dialog_id. Document fallback: 'If only name known, pass dialog_name; server resolves it via list_dialogs.'
Spec posture evidence
Inferred effective spec: 2025-06-18+.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
First recorded score · v2 rubric
54/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-23
D
54
2025-06-18+
v2
mark_dialog_for_syncwrite50/100
Enroll a dialog in local synchronization coverage for search or anchor-based reading
search_messagesread only50/100
Search for messages across dialogs or within specific dialogs
submit_feedbackread only50/100
Submit feedback when a tool response is wrong, confusing, or missing a useful capability
trace_account_messagesread only50/100
Get observable messages authored by one account with best-effort visible sampling
Tool descriptions lack 'when to use' guidance. E.g., 'list_dialogs' vs 'list_topics' overlap is not clarified, an LLM may call both without understanding the distinction. Missing recovery hints for common failures (e.g., 'if search returns no results, try list_dialogs and browse manually').
No error handling guidance in any tool description. Descriptions do not explain: Are results paginated? What happens if a dialog_id is invalid? Is a retry safe? No recovery hints, retryability classification, or error taxonomy.
Tools accepting 'exact_dialog_id' (integer) do not document human-readable alternatives. Users say 'Search in #general', not 'exact_dialog_id=123456789'. Requiring opaque IDs forces extra lookup calls and mismatches the chat interaction model.
Tools returning lists (list_messages, search_messages, list_dialogs, list_topics) do not document pagination support. Descriptions do not mention limit/offset/cursor parameters or result count constraints. Large result sets risk context window exhaustion.
trace_account_messages and search_messages use vague parameter names ('query', 'account_id'). No guidance on format (regex? fuzzy match? exact substring?). LLMs will guess incorrectly and retry with hallucinated variations.
No response shaping documented. Lists returned by list_* tools likely include verbose Telegram metadata (internal IDs, timestamps, encoding details) that waste tokens. No guidance on what fields are included or stripped.
Document pagination for list_* tools. Add to list_messages, search_messages, list_dialogs, list_topics: 'Results are paginated. Use limit (default 20, max 100) and offset/cursor parameters to navigate. Returns total_count for result estimation. Limit results to 50 items per call to conserve context.'
Clarify tool composition and dependencies. Add to get_sync_status: 'Call this before search_messages or list_messages on a new dialog. If status is not enrolled, call mark_dialog_for_sync first.' Add to get_entity_info: 'Entity param accepts Telegram username (@alice), link (t.me/alice), or user_id. If only partial info, call search_messages or list_dialogs first to find the user/channel.'
Document side effects and idempotency. Add to mark_dialog_for_sync: 'Idempotent, calling multiple times with same dialog_id is safe. No side effects beyond enrolling the dialog in sync. Enrollment is persistent; once enrolled, subsequent searches are fast.'
Strip verbose response metadata. Post-process list_messages, list_dialogs, list_topics, and trace_account_messages results to exclude internal Telegram fields (raw_request, auth_key, internal_flags, etc.). Include only: message_id, text/content, sender_id, timestamp, dialog_id, subject (for topics). Document what is returned.
Add response shaping for multi-item tools. For search_messages, list_dialogs, and list_topics, return per-item metadata so agents can chain operations. E.g., list_dialogs response includes dialog_id, name, unread_count, last_message_preview, is_forum, allowing agents to pick a dialog and then call list_topics or list_messages without extra lookups.