fast-mcp-telegram

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

Adds behavioral details beyond annotations: limitations (only own messages, text only), parse_mode specifics, and return format for both success and error cases. Aligns with annotations and provides deeper understanding.

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?

Concise yet information-dense. Every sentence adds value: purpose, constraints, parse_mode, return format, usage guidance, and doc link. Front-loaded with the main action.

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 all necessary aspects: what it does, when to use, behavioral limitations, parameter context, and return values. With output schema present, this is fully complete for an agent to use 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 already provides 100% coverage including detailed descriptions for each parameter. The description adds little beyond schema, but it does mention parse_mode in context and return format, which slightly enhances understanding. Baseline 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 clearly states 'Replace the text of an existing message in a Telegram chat' with specific verb and resource. It distinguishes from siblings by mentioning '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?

Explicitly states when to use this tool vs send_message, and includes constraints like only works on own messages and cannot edit media. This provides clear usage 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 already declare readOnlyHint, openWorldHint, and idempotentHint, so the agent knows this is a safe read. The description adds behavioral details like round-robin merging, global vs dialog-list search behavior, and the success dict shape, which go 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 three sentences, but the middle sentence is a long, dense enumeration of search modes and filter behaviors. Purpose is front-loaded, but the length and complexity reduce readability slightly.

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 the main search modes, result merging, and the success return shape, and an output schema exists. It references full documentation for more, which is acceptable. However, the mention of 'filter', 'include_peers', and 'flag-based filters' not present in the schema could confuse an agent trying to invoke the tool.

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 7 parameters have schema descriptions (100% coverage), so baseline is 3. The overall description adds context about how query interacts with date filters, but the schema already documents each parameter's purpose and defaults. No major additional semantics beyond what's 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 opens with 'Find users/groups/channels by name, username, or phone', which is a specific verb and resource. It clearly distinguishes itself from siblings like search_messages_globally by focusing on chat discovery rather than message content search.

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 global search applies (query required) versus dialog list-based search with date filters, and notes that comma-separated usernames are processed in parallel. However, it doesn't explicitly state when to prefer this over alternatives like get_chat_info, and no 'when not to use' guidance is given.

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, idempotentHint, and openWorldHint. The description adds conditional return details: 'forum chats may include topics up to topics_limit; user targets may include common_chats up to common_chats_limit,' which is useful behavioral context not provided by annotations. No 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?

Two concise sentences with a doc link. Purpose is front-loaded with no filler, and the documentation link adds optional depth without bloating the description.

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 present and annotations covering safety, the description covers purpose, success shape, conditional fields, and links to full docs. This is complete for a read-only single-target tool.

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 covers both parameters with descriptions at 100% coverage, so baseline is 3. The description adds only a redundant note about topics_limit's effect and mentions a non-parameter common_chats_limit, providing marginal value 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?

The description states 'Load profile and metadata for one user, bot, group, or channel' – a specific verb and resource, with a clear scope of a single target. It naturally differentiates from siblings like get_messages (messages) and find_chats (search).

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 makes it clear this tool is for retrieving metadata for a single chat, based on the verb and resource. It does not explicitly name alternatives or exclusions, but the context is unambiguous enough to guide selection.

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, and the description aligns with these. Beyond that, it discloses meaningful behavioral details: include_replies costs an API call per result, context is disabled when cost caps are exceeded, and the response contains messages, has_more, and optional total_count/discussion fields. This goes well beyond the structured 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 a compact, front-loaded paragraph covering purpose, key parameters, a constraint, and response fields, followed by a documentation link. Every sentence contributes value; no filler or redundancy. It is appropriately sized for a tool with 13 parameters.

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 (13 parameters, output schema present), the description provides a complete high-level picture: usage modes, key parameter roles, mutual exclusions, cost behavior, and response shape. The link to full documentation covers any remaining edge cases. The output schema handles return value details, so the description need not repeat them.

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 groups parameters into usage modes and highlights constraints (e.g., not combining message_ids with query/reply_to_id), but most of this information already appears in the parameter descriptions within the schema. No significant new semantics 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?

The description clearly states "Read or search messages in one chat" and enumerates specific modes: browse latest, search text, fetch by ids, load replies. This distinguishes it from siblings like search_messages_globally (global search) and send_message (send). The verb+resource+scope is specific and immediately understandable.

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 context on how to use the tool: use from_user for sender filtering, context for neighboring messages, include_replies for direct replies, and explicitly warns "Do not combine message_ids with query or reply_to_id." It implies per-chat scope but does not explicitly name sibling alternatives like search_messages_globally, so it stops short of a perfect 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?

The description adds context beyond the openWorldHint and destructiveHint annotations by explaining the allow_dangerous gate and stating that success returns an API result dict or normalized error. It also links to full documentation, increasing transparency though it doesn't detail error cases or side effects further.

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 three concise sentences, front-loaded with purpose, then safety, then result/links. No wasted words; every sentence earns its place and the structure is easy to scan.

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 complexity of an open-world low-level API invoke, the description covers the essential aspects: purpose, safety gate, result format, and a documentation link. With an output schema present and good annotations, it is reasonably complete, though it could briefly mention advanced usage risks or method normalization, but that is not critical.

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 covers all parameters with detailed descriptions (100% coverage), so the description adds little new parameter-level meaning. It does reinforce the allow_dangerous behavior ('Dangerous methods require allow_dangerous=true'), but this is already present in the schema, keeping the score at the baseline.

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 is a low-level Telegram API (MTProto) invoke for methods not wrapped by other tools, using the specific verb 'invoke' and identifying the resource. It distinguishes itself from sibling tools by explicitly positioning itself as a fallback for unsupported 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?

It provides explicit guidance: use for methods not wrapped by other tools, and requires allow_dangerous=true for dangerous methods. This gives clear context for when to use this tool versus alternatives, though it doesn't enumerate specific sibling exclusions beyond 'other 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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering safety and side effects. The description adds useful behavioral context such as the return format (message list and metadata dict) and the caveat that global search ignores include_total_count, which goes beyond 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 and stays concise at five sentences. It includes a documentation link and essential behavior notes, though one sentence duplicates schema information (include_total_count), making it slightly less efficient than ideal.

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, 1 required), the description covers the global scope, query syntax, filters, return value, and a special behavior. The output schema handles return details, and the documentation link provides further depth, making it adequately complete for selection and invocation.

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 already documents all parameters. The description repeats the comma-separated query semantics and filter types but adds minimal new parameter-level insight beyond what the schema provides, hence the baseline score of 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 clearly states it searches all Telegram chats globally, explicitly contrasting with per-chat search ('not scoped to one chat'). It uses a specific verb+resource combination and distinguishes itself from sibling tools like get_messages.

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 context on when to use this tool ('Search all Telegram chats at once'), implying global vs per-chat use cases. However, it does not explicitly name alternative tools or state exclusion criteria, so it falls 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?

The description discloses many behavioral traits beyond annotations: parse_mode=rich cannot be combined with files, file attachments make the message a caption, channel posts with reply_to_id automatically post in the linked discussion group, and return/error formats are specified. It also notes that local paths work only in stdio mode. No contradiction with the annotations (openWorldHint, 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?

The description is relatively long but every sentence adds value—no fluff or repetition. It front-loads the core purpose, then covers parameters, edge cases, return values, and alternatives in a logical order. The documentation link is a useful appendix without cluttering the main 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?

Given the tool's complexity (5 params, 2 required, enums, output schema), the description is remarkably complete. It explains return value structure (message_id, status, error handling), critical constraints (rich cannot combine with files), platform-specific behavior (stdio local paths), and documents all parameter semantics. No gaps remain.

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%, but the description adds substantial context: chat_id formats (numeric, username, 'me'), files support data URIs and local path restrictions, parse_mode enum semantics with rich message dialect detection, and reply_to_id behavior for forums and channels. This goes well beyond the schema definitions.

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: "Send text and optional file attachments to a Telegram chat." It identifies the specific verb (send), resource (Telegram chat), and scope (text and optional file attachments), and it distinguishes from siblings by naming alternatives like 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?

Explicit guidance is provided: "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." This directly tells the agent when to choose this tool versus alternatives, exceeding simple 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?

The description discloses temporary contact creation, parse_mode behaviors, and the rich/files incompatibility, which go beyond the openWorldHint and destructiveHint annotations. It also mentions contact_was_new/contact_removed in the result, giving insight into side effects.

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, using three sentences for purpose, mode details, and result hints, plus a documentation link. Every sentence adds unique information without 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 8-parameter complexity and the presence of an output schema, the description covers core behaviors, constraints, and result characteristics. It could include more caveats like local-path restrictions, but the schema already covers those, making it 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?

Schema coverage is 100%, providing a baseline 3. The description adds value by clarifying parse_mode semantics, highlighting the rich + files conflict, and noting ephemeral contact flags, exceeding baseline.

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 'Send to a phone number' with a specific verb and resource, clearly distinguishing it from the sibling send_message tool which likely targets chat IDs. It also mentions temporary contact creation, clarifying 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 usage when a phone number is available, which contrasts with send_message. However, it does not explicitly name alternatives or state when not to use this tool, so it falls 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.