Fast MCP Telegram

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

Beyond annotations (idempotent, destructive, open world), the description adds critical context: only editable by the sender, only text, success/error response format, and return fields. 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?

Every sentence adds value: purpose, constraints, return format, usage guidance, and doc link. No fluff, well structured with most critical info first.

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 input schema coverage, annotations, and output schema, the description is complete: covers what, constraints, errors, usage, and links to full docs. No missing context.

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%, baseline 3. The description adds value by explaining parse_mode detect behavior and clarifying message_id source ('from get_messages or Telegram'). Slight improvement over 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 states the tool replaces text of an existing message, with specific constraints (only own messages, text only). It distinguishes from siblings like send_message.

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?

Explicitly says when to use: 'Use edit_message to update a previously sent message; use send_message to create new ones.' Also mentions it only works on messages sent by the authenticated account, guiding appropriate use.

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 mark the tool as read-only and idempotent. The description adds valuable behavioral context, such as how search scope changes based on parameters, the role of include_peers and flag-based filters, and the result format (dict with 'chats' key). This goes beyond the 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?

The description is concise with four sentences, front-loading the main purpose. It uses clear phrasing and ends with a link to full documentation. Every sentence serves a purpose with no redundancy.

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 (7 parameters, two search modes, filter behaviors), the description covers search types, filter mechanics, and result format. The output schema exists, so return values are well-documented. A link to full documentation ensures 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%, so the schema itself documents all parameters well. The description adds general context about search modes but does not provide parameter-specific details beyond the schema. This is adequate, as baseline for high coverage is 3.

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 explicitly states the tool finds users/groups/channels by name, username, or phone. It clearly distinguishes from siblings like search_messages_globally (for messages) and get_chat_info (for single chat details), and explains the two search modes (global vs. dialog list).

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 clear guidance on when to use global search (query required) versus dialog list search (when min_date, max_date, or filter is used). It also explains filter behaviors. However, it does not explicitly state when not to use this tool or compare directly with alternatives, but the context is sufficient.

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 indicate readOnlyHint, idempotentHint, openWorldHint. Description adds that forum chats may include topics up to topics_limit, which is useful but not extensive. No contradictions.

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 concise sentences: core purpose, success behavior with forum note, and link to full docs. No wasted words, front-loaded.

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?

Output schema exists, so return values need not be detailed. Description covers success outcome and a key parameter effect. Slightly missing error handling or preconditions, but adequate.

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%, baseline 3. Description adds context to topics_limit by explaining its role in forum chats, and chat_id is well-described 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?

Description explicitly states 'Load profile and metadata for one user, bot, group, or channel.', using a specific verb and resource, and clearly differentiates from siblings like get_messages or find_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?

Implicitly suggests use for a single chat, but no explicit when-to-use, when-not-to-use, or alternatives provided. Lacks guidance on when to prefer find_chats or search_messages_globally.

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 (readOnlyHint, openWorldHint, idempotentHint) already indicate safety. The description adds context about response fields (messages, has_more, optional total_count, discussion) and a documentation link, enriching 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 concise (3-4 sentences), front-loaded with purpose and modes, then critical usage note and success info. No redundant sentences.

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 (10 parameters, 1 required, output schema exists), the description covers modes, constraints, and return fields succinctly. A documentation link fills any remaining gaps. Slightly more detail on interaction between parameters could be added, but it's largely 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?

Schema coverage is 100%, so baseline is 3. However, the description adds grouping by mode, mutual exclusivity warnings, and clarifies chat_id formats (numeric id, username, 'me'). This extra context justifies a 4.

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 reads or searches messages in one chat, listing specific modes (browse latest, search text, fetch by ids, load replies). It distinguishes from sibling tools like search_messages_globally (global vs. per-chat) and find_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?

Explicitly warns not to combine message_ids with query or reply_to_id, and implies when to use each mode. More could be said about when not to use this tool at all, but the guideline is clear and actionable.

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 destructiveHint and openWorldHint. The description adds that dangerous methods require allow_dangerous=true and mentions the return format (API result dict or normalized error), which goes beyond 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?

Two sentences, front-loaded with purpose, then usage, then result. Every sentence is informative without 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?

The description covers purpose, usage, safety, and result format. With output schema present, it doesn't need to detail return structure. Could mention potential errors more explicitly, but the mention of 'normalized error' suffices.

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 adds minimal extra meaning beyond the schema, only reiterating the allow_dangerous flag concept.

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 it is a low-level Telegram API (MTProto) invoke for methods not wrapped by other tools, which distinguishes it from sibling tools that wrap specific endpoints.

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 'for methods not wrapped by other tools', indicating when to use. It also warns about dangerous methods requiring allow_dangerous=true. However, it doesn't explicitly list when not to use it or name alternative tools.

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 adds behavioral context beyond annotations: it notes that global search ignores include_total_count, which is not captured by readOnlyHint or idempotentHint. It also mentions optional filters. No contradictions 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?

The description is two sentences plus a link, front-loaded with the key purpose. Every sentence adds value, no fluff. Efficient 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 8 parameters and an output schema, the description covers the main purpose, key filters, and a behavioral note. It could mention default limit and auto_expand_batches, but with output schema present and link to full docs, it is sufficiently complete. Minor gap in fully explaining all parameters.

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%, so baseline is 3. The description adds value by explaining query terms are comma-separated and OR-style, and clarifies that public filter does not apply to private DMs. It also mentions that global search ignores include_total_count, which is a behavioral nuance not in schema descriptions. Adds meaningful context beyond 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 states the tool searches all Telegram chats at once, distinguishing it from siblings like get_messages which are scoped to one chat. The verb 'search' and resource 'messages globally' 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?

The description explains comma-separated query terms and optional filters, and notes that global search ignores include_total_count. While it doesn't explicitly state when to use this tool versus alternatives (e.g., get_messages for single chat), the global scope is clearly indicated, and a link to full documentation is provided. Slight omission of explicit usage context.

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 include destructiveHint: true, but the description adds context: files turn text into caption, reply_to_id behavior for forums/channels, and the success/error return format. It does not contradict 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?

The description is front-loaded with the main action, then details. Each sentence adds value, no fluff. It references full documentation externally, keeping the inline description compact.

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 input schema fully describes all parameters and the output schema is described (success/error dicts), the description is complete. It covers the tool's behavior, limitations, and usage context.

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?

All 5 parameters have descriptions in the schema (100% coverage). The description adds behavioral meaning: reply_to_id supports forum topics and discussion groups, parse_mode can be auto-detected, files support various URL types. This goes beyond the schema details.

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 'Send text and optional file attachments to a Telegram chat', specifying verb ('send'), resource ('message to Telegram chat'), and scope. It explicitly distinguishes from siblings by naming edit_message and send_message_to_phone.

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 explains the automatic behavior for channel posts with reply_to_id.

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 adds behavioral context beyond annotations: it may create a temporary contact, and the success response includes fields like contact_was_new and contact_removed. Annotations already flagged destructive hint, so the description provides useful elaboration without contradiction.

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 and a link, front-loading the core action. It is concise without wasted words, though a bit more detail on side effects could fit.

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 an output schema and 100% schema coverage, the description sufficiently covers the tool's behavior, mentioning return values and linking to full docs for completeness. It adequately addresses the 8-parameter 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?

Schema coverage is 100% with descriptions, so baseline is 3. The description does not add meaning beyond what the schema already provides for parameters like phone_number, message, or remove_if_new.

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 sends a message to a phone number, potentially creating a temporary contact. It distinguishes from siblings like 'send_message' which targets chat IDs, and other tools like 'edit_message' or 'get_messages' that serve different purposes.

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 use when sending to a phone number, but does not explicitly state when not to use it or provide comparisons to alternatives like 'send_message'. It lacks guidance on prerequisites such as requiring the number to be on Telegram.

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