fast-mcp-telegram

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

Annotations provide destructiveHint, idempotentHint, and openWorldHint, but the description adds rich behavioral context: the restriction to the authenticated account's messages, text-only limitation, explicit success/error dict shapes (including status='edited' and edit_date), and parse_mode side effects (rich messages setting rich=true). 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?

The description is front-loaded with the core purpose, followed by constraints, return format, and usage guidance. Every sentence adds value and the structure is logical, despite the length. No fluff or 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?

The description is complete for a mutation tool: it covers purpose, constraints, success/error formats, usage alternatives, and links to full documentation. The schema covers parameter syntax, and annotations cover safety hints. Nothing essential 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 schema already documents all parameters fully. The description does not add new meaning beyond the schema; it merely restates parse_mode behavior already covered. Thus the baseline 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 opens with 'Replace the text of an existing message in a Telegram chat,' a specific verb+resource+action. It clearly distinguishes from siblings by stating 'Use edit_message to update a previously sent message; use send_message to create new ones.'

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 explicitly names the alternative tool (send_message) for creating messages. It also provides when-not-to-use constraints: 'Only works on messages sent by the authenticated account' and 'Cannot edit media or other message attributes — text only.'

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 establish read-only, open-world, and idempotent behavior. The description adds valuable context beyond that, such as parallel search in comma-separated usernames and round-robin result merging, plus mode-dependent behavior. 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 dense and technically complex, mixing multiple modes and filter behaviors into long sentences. It is front-loaded with the purpose but the second sentence is overloaded with semicolon-separated conditions, making it harder to parse quickly. It could be restructured into clearer segments.

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 output schema and annotations, the description is largely complete: it covers the success return shape ('dict with key chats'), explains parameter modes, and points to full documentation. However, it references 'include_peers filters' and 'flag-based filters' that do not correspond to any schema parameters, which may confuse users.

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 baseline is 3. The description adds meaning by explaining that certain parameters (min_date, max_date) switch the search mode from global to dialog list, and that query is required only for global search, enriching the schema's per-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 opens with a specific verb and resource: 'Find users/groups/channels by name, username, or phone.' This clearly states the tool's function and differentiates it from sibling tools like search_messages_globally (messages) and get_chat_info (individual chat details).

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 when to use global search versus dialog list filtering based on parameters (e.g., 'Global search (query required)... with min_date, max_date, or filter...'), providing clear context for selecting search modes. It does not explicitly name alternatives, so it stops short of a 5.

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 some return-shape and conditional field context (topics, common_chats), but this largely repeats information in the schema and output schema. No additional behavior such as error cases or rate limits is disclosed.

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 compact and front-loaded: the core purpose appears first, conditional behavior follows, and a documentation link is tucked at the end. It loses one point for slight redundancy with the schema descriptions, but there is no filler or ambiguity.

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 that an output schema exists, all parameters are fully described in the schema, and annotations cover the read-only/idempotent nature, the description is largely complete for invocation. The only notable omission is explicit routing guidance against sibling tools, but that is already assessed under usage guidelines.

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%, with each parameter already well documented and defaults provided. The description adds no new parameter-level meaning beyond restating that topics_limit and common_chats_limit bound optional result fields, so the baseline of 3 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 states a specific verb ('Load') and a precise resource ('profile and metadata for one user, bot, group, or channel'). This clearly scopes the tool and distinguishes it from message-oriented or search-oriented siblings. The target-kind enumeration adds immediate practical clarity.

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 the tool—when you need info about a single chat entity—but it gives no explicit when-not-to-use guidance or alternatives. It does not mention sibling tools like find_chats or get_messages, so an agent must infer the decision boundary.

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 the readOnlyHint and idempotentHint annotations, the description discloses meaningful behavioral traits: include_replies 'costs one API call (not batchable),' context is 'Disabled when result count exceeds cost-based caps,' and the server-side per-chat filter for from_user. These details inform the agent about side effects and limitations without contradicting 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 compact yet information-dense, front-loading the core action in the first sentence and then detailing key usage points and constraints. It avoids fluff and ends with a documentation link, earning each sentence's place.

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?

For a tool with 13 parameters, an output schema, and read-only annotations, the description provides a comprehensive overview: it lists all major modes, notes cost-related behavior, states success response fields, and links to full documentation. This is sufficient for an agent to select and invoke the tool correctly without needing to infer critical details.

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 descriptions already cover all 13 parameters with 100% coverage, including the mutual exclusivity of message_ids and the per-chat nature of from_user. The description's parameter-related guidance, such as 'Use context to include neighboring messages,' largely repeats what the schema already states, adding minimal semantic value beyond the structured fields.

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 within one chat, enumerating four distinct modes: browse latest, search text, fetch by ids, and load replies. The phrase 'in one chat' explicitly distinguishes it from the sibling tool search_messages_globally, establishing scope and resource.

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 usage context, such as 'Use from_user to filter by sender (server-side, per-chat only)' and 'Do not combine message_ids with query or reply_to_id,' which set expectations for parameter combinations. However, it does not explicitly mention when to prefer the global search sibling or exclude this tool for cross-chat searches, so it stops short of full when-not 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?

Beyond annotations that only indicate openWorldHint and destructiveHint, the description discloses concrete behavior: dangerous methods are blocked unless allow_dangerous=true, PII/credential-shaped fields are stripped by default, include_sensitive=true returns the raw payload, bare message id requests without a peer field are refused, and messages.GetHistory cannot address forum topics. 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?

The description is front-loaded with purpose, then safety, result semantics, and edge-case constraints. Each sentence contributes distinct information, and the documentation link provides an exit for deeper details without bloating the text.

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?

For a broad low-level invoke tool, the description covers safety gating, sensitive-data filtering, peer-binding requirements, a difficult forum-topic edge case, and points to full documentation. Since an output schema exists, the response shape does not need to be re-explained.

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. Description adds operational meaning for params_json through the chat-binding rule and forum-topic caveat, and reinforces include_sensitive behavior by naming phone and access_hash. This is modest but genuine added value over 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 says 'Low-level Telegram API (MTProto) invoke for methods not wrapped by other tools,' naming the verb, resource, and scope. It also differentiates itself from the higher-level sibling tools by explicitly framing itself as the fallback for unwrapped methods.

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?

States clearly to use it for methods not wrapped by other tools. It gives explicit routing guidance: use channels.GetMessages or messages.GetHistory with the chat binding, and messages.Search or get_messages for forum topics. It also explains when allow_dangerous=true is required.

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 a non-obvious behavior (global search ignores include_total_count) and states the success return shape ('message list and metadata dict'). This adds context beyond the readOnly/idempotent annotations. No contradictions exist with 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?

Three concise sentences front-load the core purpose, followed by key search behavior and a documentation link. Every sentence earns its place with no 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 8-parameter schema with full descriptions, the description covers global scope, return format, and a behavioral caveat, plus a documentation link for deeper reference. It's sufficiently complete for an agent to select and invoke the tool correctly without needing additional information.

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 rich parameter descriptions, so the baseline is 3. The description restates query semantics ('Comma-separated query terms') and summarizes filter options, but doesn't add significant new parameter details beyond what the schema already provides. The include_total_count caveat is a small extra.

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 action ('Search all Telegram chats at once') and resource (messages across all chats). The parenthetical 'not scoped to one chat' explicitly differentiates it from sibling tools like get_messages, giving it a distinct and unambiguous purpose.

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 implies use when needing cross-chat search by stating 'Search all Telegram chats at once' and contrasting with scoped search. It also provides a specific behavioral caveat ('Global search ignores include_total_count'). However, it doesn't explicitly name alternative tools for single-chat search, so the guidance is clear but not fully explicit.

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 provide openWorldHint and destructiveHint, but the description goes further by disclosing specific behaviors: parse_mode dialects auto-detected, file attachments treated as captions, automatic posting in linked discussion groups for channel replies, and detailed success/error dict structures. This adds substantial context beyond the annotations and aligns with destructiveHint.

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 earns its place: it covers purpose, parameter nuances, file behavior, channel posting, return values, and alternatives in a compact paragraph. The optional documentation link is a minor extra that doesn't detract.

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 is fully complete for a 5-parameter tool with complex interactions: it explains parse_mode variants, reply_to scenarios, file handling, and success/error formats. The output schema exists, but the description redundantly specifies return fields (message_id, date, chat, etc.) and also covers edge cases like rich messages.

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 descriptive parameter docs, so baseline is 3. The description adds value by explaining interactions between parameters (e.g., files make message a caption, parse_mode=rich cannot combine with files) and the return payload structure, though much is redundant with schema 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 'Send text and optional file attachments to a Telegram chat' with a specific verb and resource. It explicitly distinguishes from sibling tools by mentioning alternatives like edit_message and send_message_to_phone, and includes detailed context about reply-to behavior and channel discussion groups.

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 offers explicit when-to-use guidance: 'Use send_message to create new messages; use edit_message to modify existing ones' and 'Use send_message_to_phone when targeting a phone number instead of a chat_id.' It also clarifies constraints like parse_mode=rich not combinable with files and channel post behavior.

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=true, and the description adds valuable context about temporary contact lifecycle ('may create a temporary contact', 'contact_was_new / contact_removed') and the rich mode restriction. This goes beyond the annotation without contradicting it.

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 documentation link. It front-loads the primary purpose, includes the most important caveat, and mentions success output fields in a compact way. 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?

Given the tool's complexity (8 parameters, output schema, annotations), the description covers the core purpose, temporary contact behavior, rich mode limitation, and result fields. It doesn't explain prerequisites like 'phone must be on Telegram', but that is in the schema. A documentation link further fills gaps. Sufficiently 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 schema covers 100% of parameters with detailed descriptions, so the baseline is 3. The description's note that 'parse_mode=rich cannot be combined with files' is helpful but is also present in the schema's parse_mode description. No additional parameter semantics provided 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 opens with 'Send to a phone number', clearly stating the action and specific resource. It also mentions the temporary contact creation and text/file sending, which distinguishes it from sibling tools like send_message that likely operate on existing 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?

It clearly implies the use case (when you have a phone number) by starting with 'Send to a phone number'. It does not explicitly mention alternatives or exclusions, but the phone-number focus is clear enough to guide tool selection. Lacks an explicit 'use send_message instead when you have a chat ID' style note, so not a 5.

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