Fast MCP Telegram

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

Beyond annotations (openWorldHint, idempotentHint, destructiveHint), the description discloses important behavioral traits: it only works on the authenticated account's own messages, cannot edit media (text-only), explains parse_mode behavior including rich message dialect auto-detection, and describes success/error response structures with specific fields. It also notes that 'parse_mode="rich" cannot be combined with files' in the schema, but the description adds operational context about response formats and error scenarios, significantly enhancing transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is information-dense but well-structured. It starts with the primary purpose, then constraints, parameter semantics, return values, usage guidance, and a documentation link. While slightly lengthy, every sentence provides relevant context. It earns a 4 for being comprehensive without excessive wordiness, though it could be trimmed slightly by omitting the full response schema description if an output schema is present.

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

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

Given the tool's complexity (4 parameters, output schema present, annotations present), the description is remarkably complete. It covers purpose, restrictions, parameter behavior, success/error outputs, and usage guidance. The inclusion of specific error examples and the rich message format details ensures the agent can confidently invoke and interpret results. The documentation link provides additional fallback. This meets the highest standard of contextual completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed parameter descriptions, so baseline is 3. The description adds value by clarifying that the 'message' parameter is text-only (correcting a potential misinterpretation from the schema's 'When sending files, used as caption'), and it summarizes parse_mode options with the rich dialect auto-detection. This goes beyond pure schema repetition, thus a 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Replace the text of an existing message in a Telegram chat.' It specifies the resource (messages in Telegram chats), the action (replace text), and distinguishes from siblings by explicitly noting 'Use edit_message to update a previously sent message; use send_message to create new ones.' It also clarifies scope limitations: 'Only works on messages sent by the authenticated account' and 'Cannot edit media or other message attributes — text only.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use the tool: 'Use edit_message to update a previously sent message; use send_message to create new ones.' It also implies when not to use it by stating 'Cannot edit media,' effectively directing media editing/sending elsewhere. This is clear and actionable, going beyond mere implication.

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

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

The description discloses useful behavioral details like parallel comma-separated search, round-robin merging, and mode switching based on parameters, adding value beyond the readOnly/idempotent annotations. However, it references parameters (include_peers, flag-based) that do not exist in the input schema, which undermines transparency and adds confusion.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is moderately concise with a clear front-loaded purpose, but includes technical jargon (GetPeerDialogs, flag-based filters) and references to undocumented parameters, making it less clear than it could be. Every sentence has some content, but some could be streamlined or clarified.

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

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

The tool is complex with multiple search modes, and the description references parameters not present in the schema, creating ambiguity about how to properly invoke the tool. The output schema exists and the return format is mentioned, but the mismatch between description and schema leaves significant gaps in understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema documents all 7 parameters with descriptions, so baseline is 3. The description adds some context about batch lookup and search modes, but does not compensate for the phantom parameters mentioned. It adds marginal value beyond the schema's already-good parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds users/groups/channels by name, username, or phone, which is specific and distinguishes it from message-searching siblings. The verb 'Find' and resource 'users/groups/channels' are unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides conditional behavior for different search modes (global vs dialog list) but does not explicitly state when to prefer this tool over alternatives like search_messages_globally. It implies usage scenarios but lacks explicit exclusions or alternative recommendations.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it notes that the result may include topics up to topics_limit for forums and common_chats up to common_chats_limit for user targets, which is not fully captured by the schema. It also states the success return shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with purpose, and includes a documentation link. Every sentence earns its place, providing key behavior details without redundancy or fluff.

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

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

Given the tool's low complexity, rich annotations (readOnly, openWorld, idempotent), a full output schema, and a documentation link, the description is complete. It covers the main behavioral nuances (topics_limit, common_chats_limit) and success condition, so no critical information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema; it merely mentions topics_limit in a sentence, which repeats the schema description. The chat_id parameter is fully defined in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Load') and resource ('profile and metadata for one user, bot, group, or channel'), clearly distinguishing it from siblings like get_messages (which retrieves messages) and find_chats (which searches chats). It precisely defines the tool's scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool: whenever you need profile/metadata for a specific chat target. It provides clear context but does not explicitly mention exclusions or alternatives. However, the sibling tool list makes the differentiation obvious, so this is a minor gap.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description doesn't need to restate safety. It adds valuable details like 'include_replies to fetch up to 5 direct replies', the mutual exclusion constraint, and the success field list ('messages, has_more, optional total_count and discussion fields'). It also points to full documentation, enhancing transparency. This goes well beyond the annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a tightly packed paragraph of about 120 words. It front-loads the core purpose, then gives parameter guidance in order of relevance, ends with success fields and a docs link. Every sentence conveys actionable info—no filler, no redundancy. The structure flows logically from 'what it does' to 'how to use it' to 'what to expect'.

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

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

Given the tool has 13 parameters, an output schema, and multiple modes (browse, search, fetch by ids, replies), the description covers the essential usage scenarios and constraints. It mentions the success response shape and links to full docs for edge cases. The presence of a rich output schema means the description doesn't need to repeat field details, yet it still summarizes what the caller should expect. This is complete for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% coverage with detailed per-parameter descriptions, so the baseline is 3. The description elevates this by explaining how parameters work together (e.g., 'Use context to include neighboring messages and reply chains around each result', 'Use include_replies to fetch up to 5 direct replies per result'), and clarifies positional semantics like 'Use reply_to_id with thread_scope' (implicitly). It also states the per-chat limitation of from_user. This adds integrative meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with 'Read or search messages in one chat' followed by explicit modes: 'browse latest, search text, fetch by ids, or load replies to a message'. This clearly distinguishes it from siblings like search_messages_globally by scoping to a single chat. The verb 'Read or search' is specific and the resource ('messages in one chat') is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides concrete usage guidance for several parameters ('Use from_user to filter by sender', 'Use context to include neighboring messages', 'Use include_replies to fetch up to 5 direct replies') and warns against invalid combos ('Do not combine message_ids with query or reply_to_id'). It stops short of explicitly naming alternative tools, though the 'in one chat' scope implicitly contrasts with global search. This is strong guidance but lacks a direct 'when not to use' statement.

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

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

The description complements the destructiveHint annotation by explaining that dangerous methods require allow_dangerous=true, and discloses success/error return behavior. It also points to full documentation for deeper context, though it could elaborate on what 'normalized error' means.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences front-load the core purpose, then address safety and results, and finish with a documentation link. No wasted words; succinct and well-structured.

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

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

Given the tool's complexity, the presence of an output schema, and annotations, the description sufficiently covers the main usage scenarios and danger gating. The documentation link compensates for any missing details, though a brief example or note on normalization would make it fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides comprehensive descriptions for all four parameters, including the discriminator convention for nested TL objects. The description adds only minimal value beyond the schema, mainly reinforcing the allow_dangerous behavior, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that this is a low-level Telegram API (MTProto) invocation tool for methods not wrapped by other tools, which separates it from siblings like send_message or get_messages. The verb 'invoke' and resource 'MTProto' are specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says to use this tool for methods not covered by other tools, providing clear guidance on when to invoke it versus using wrapped alternatives. The danger caveat about allow_dangerous=true adds practical usage direction.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is known. The description adds a useful behavioral quirk: global search ignores include_total_count, and it clarifies that success returns a message list and metadata dict, which supplements the output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then concisely lists key features and a behavioral caveat, and ends with a documentation link. Every sentence earns its place with no redundant or vague content.

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

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

Given 8 parameters, a rich schema, an output schema, and annotations, the description provides sufficient context including global scope and the include_total_count quirk. It could be more explicit about alternatives to scoped search, but no critical information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, all 8 parameters are fully documented in the schema. The description restates comma-separated terms and optional filters but adds no new parameter semantics beyond what the schema already provides; the include_total_count caveat is already present in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as performing a global search across all Telegram chats, explicitly noting it is not scoped to one chat. This verb-resource-scope combination distinguishes it from sibling tools like get_messages that are chat-specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context that this is for searching across all chats at once, contrasting with scoped search. However, it does not explicitly name alternative tools for scoped searches or state when not to use this tool, leaving a small gap in guidance.

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

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

Annotations are minimal (openWorldHint, destructiveHint), so the description carries the burden. It discloses key behavioral details: parse_mode='rich' cannot combine with files, text becomes caption when files are present, channel post reply_to_id auto-posts in discussion group, and precise success/error dict shapes. No contradiction 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Although longer than two sentences, every sentence carries necessary information. The description is front-loaded with the core action, then layers details logically (format, files, reply, channel behavior, result, alternatives). There is zero fluff; redundant details are delegated to a documentation link.

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

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

This is a complex tool with 5 parameters, an output schema, and nontrivial edge cases (parse modes, file handling, reply-to variations, discussion groups). The description covers all of these and also states the success/error return structures, making it complete for selecting and invoking correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, giving a baseline of 3, but the description adds significant value: it explains file source types (URLs, local paths, data: URIs), parse_mode dialect detection, reply_to_id semantics for forums/channels, and how 'me' works for chat_id. This goes well beyond the schema's own descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Send text and optional file attachments to a Telegram chat' – a specific verb, resource, and scope. It clearly distinguishes send_message from edit_message and send_message_to_phone by naming them and stating their different use cases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance: 'Use send_message to create new messages; use edit_message to modify existing ones. Use send_message_to_phone when targeting a phone number instead of a chat_id.' It also covers channel reply behavior and parse_mode rules.

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

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

Beyond annotations (destructiveHint, openWorldHint), the description discloses that it may create a temporary contact, can remove it if applicable, and that rich parse mode cannot be combined with files. It also mentions success response fields (contact_was_new/contact_removed), adding significant context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with main purpose, each sentence adds value: primary action, parse_mode constraints, and success result. No fluff or repetition.

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

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

With 8 parameters and an output schema, the description covers main behavior, constraints, and success result, plus a link to full docs. It lacks explicit error handling or preconditions (e.g., phone must be on Telegram, though that's in schema). Overall adequate for tool selection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with each parameter documented, so baseline is 3. The description adds some context (e.g., rich mode auto-detection, success fields) but does not significantly enhance parameter-level semantics beyond what schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Send' and resource 'phone number', and explains the temporary contact creation behavior. This distinguishes it from sibling tools like 'send_message', which likely targets chats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies when to use this tool: when sending to a phone number. However, it does not explicitly contrast with alternatives like 'send_message', nor does it state exclusions (e.g., use 'send_message' for existing chats). Thus no explicit alternative guidance.

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