telegram-mcp
Server Quality Checklist
Latest release: v0.1.0
- Disambiguation3/5
Many tools overlap in purpose (e.g., tg_notify/tg_mute/tg_alert for notifications; tg_history/tg_message/tg_export/tg_unread for reading messages), and the large number of tools makes selection harder. Detailed descriptions help, but an agent could easily pick the wrong tool when multiple cover similar actions.
Naming Consistency2/5All tools share the tg_ prefix, but beyond that the naming is erratic: bare verbs (tg_send), bare nouns (tg_contacts), verb_noun (tg_send_file), and noun_verb (tg_chat_edit) are mixed without a clear convention. The inconsistent action-object order makes patterns unpredictable.
Tool Count1/5With 70 tools, this server is extremely heavy. Even for a comprehensive Telegram client, 70 is far beyond the typical well-scoped range (3-15) and likely to overwhelm agents, increasing selection errors and processing costs.
Completeness5/5The tool surface is remarkably comprehensive, covering messaging, media, scheduling, folders, admin, accounts, stories, bots, search, translation, and moderation. It supports nearly every Telegram workflow an agent might need, with only minor gaps like profile editing.
Average 4.1/5 across 70 of 70 tools scored. Lowest: 2.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 8 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, and the description discloses almost no behavioral traits. It does not mention side effects, reversibility, permissions, or what happens to the chat upon archiving. The phrases 'move' and 'back out' give only a minimal hint of state change.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundant content. It is front-loaded with the core action and earns its place without wasting words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description lacks crucial details such as chat identifier format, undo semantics, and behavioral effects. The presence of an output schema helps, but the description alone is insufficient for an agent to confidently invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only minimally explains the 'undo' parameter via 'or back out of it.' The 'chat' parameter format is entirely unaddressed. While parameter names are self-explanatory, the description fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: moving a chat to the archive or back out. It uses a specific verb+resource and is distinguishable from siblings by its archive focus, but it does not explicitly name alternative tools, so it misses the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance or alternatives are provided. The description implies usage for archiving/unarchiving but does not explain when to prefer this over chat deletion, muting, or other sibling tools, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It reveals only the basic action (sending a location pin) and the actor ('as the user'), but omits any side effects, permission requirements, error handling, or what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is appropriately front-loaded, though it is so brief that it sacrifices completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description lacks any context for use: no indication of chat type, coordinate system, expected behavior, or relationship to sibling send tools. The presence of an output schema does not offset the missing usage and parameter guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the three parameters (chat, latitude, longitude). It adds no information beyond the schema's property titles, failing to compensate for the lack of parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Send' and resource 'location pin', clearly distinguishing it from sibling tools like tg_send or tg_send_file. The phrase 'as the user' adds context about who is performing the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention exclusions, prerequisites, or scenarios where other sending tools might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It states the data is for supergroups and lists fields, but doesn't disclose read-only behavior, absence of side effects, sorting, pagination, or permissions. The description adds minimal context beyond the tool's purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded, with the first sentence summarizing output and the second providing a cross-reference to a sibling tool. No filler, but it omits parameter explanations, making it concise but slightly under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters and no annotations, the description is incomplete. It doesn't explain limit/query usage, return format beyond field names, or edge cases (e.g., non-supergroup chats). The presence of an output schema helps, but the description still leaves important gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explain 'chat', 'limit', or 'query'. While 'chat' is somewhat implied as the supergroup identifier, 'limit' and 'query' are completely unspecified. The description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as returning forum topics for a supergroup, enumerating specific fields (id, title, unread count, closed/pinned state). It also distinguishes this listing tool from tg_history for reading a single topic, though the verb is implied rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for listing all topics, but the only explicit guidance is a pointer to tg_history for reading a single topic. It lacks explicit 'use this when' or 'not when' conditions, and doesn't mention when query or limit parameters would be relevant.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, but it only lists output fields and does not disclose potential errors, authentication requirements, rate limits, or side effects. While 'Details about' implies a read operation, this is not explicitly stated, and no behavioral context beyond the returned fields is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently communicates the tool's purpose and output fields with no filler. Every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, output schema exists), and the description covers the purpose and expected output fields. However, it lacks input format details and usage guidance, which may lead to incorrect invocation, especially without annotations. It is minimally complete but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies that the 'chat' parameter can refer to a chat or a person, but it does not explain the expected format (e.g., numeric ID, username, phone number). This leaves important ambiguity for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns details about a chat or person, listing specific fields (id, username, type, member count, bio). This distinguishes it from sibling tools that handle participants, contacts, or bot-specific info, though it lacks an explicit verb like 'get' or 'fetch'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to fetch basic chat/person information, but it provides no explicit guidance on when to use it over alternatives or any exclusions/prerequisites. It does not mention relationship to sibling tools like tg_participants or tg_resolve.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the burden of behavioral disclosure. It simply states 'forward messages' without mentioning side effects, whether the original message is copied or moved, required bot permissions, or any rate limits. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler or redundancy. It communicates the core action efficiently, though it is under-specified in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 required parameters and an output schema, the description is too minimal. It does not explain how chats are identified (IDs, usernames), how message_ids are used, or what result to expect. The output schema may cover return values, but the description lacks operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions (0% coverage), and the description only implicitly covers 'from_chat' and 'to_chat' via 'from one chat to another'. The critical 'message_ids' parameter is entirely omitted, leaving its semantics unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'forward' with resource 'messages' and clearly indicates the operation from one chat to another. It is unambiguous and distinguishes from sibling tools like tg_send (sending new messages) or tg_edit (modifying messages).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites, permissions, or exclusions. The description is purely functional and gives no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It only states the content of the output (drafts and chats) but does not indicate whether the operation is read-only, whether it requires authentication, how it handles large accounts, or if there are any side effects. The description is more of a return-value summary than a behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the tool's output. Every word contributes meaning, and it is immediately clear what the tool does. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameterless tool with an output schema, this description is minimally adequate. However, it lacks any context about when to use it, how it relates to other draft/schedule tools, or potential edge cases (e.g., empty drafts, archived chats). The output schema may cover return structure, but the behavioral and usage gaps lower completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema trivially covers everything. The description adds no parameter-specific meaning because there are none to describe. Per the rubric, a parameterless tool with full schema coverage earns a baseline score of 4, which is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns every unsent draft along with the associated chat. While it lacks an explicit verb like 'list' or 'get', the phrase 'Every unsent draft in the account' unambiguously defines a listing operation. It distinguishes from sibling tool 'tg_draft' (singular) by implying aggregate retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of tg_draft for individual drafts, nor any context on filtering, pagination, or limitations. It simply states what the tool returns, leaving the agent to infer usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden for behavioral disclosure. It discloses the ownership restriction but omits side effects (e.g., old text is overwritten, 'edited' marker), permission requirements, and failure conditions for editing messages.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words and the core information is front-loaded. The brevity is appropriate for a simple tool and every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values are covered, but the lack of parameter documentation and behavioral context makes the tool only partially complete. For a simple three-parameter edit, the minimal description plus schema is nearly usable, but missing edge-case behavior prevents full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain the parameters. The phrase 'one of your own sent messages' hints that message_id refers to an existing message and text is the new content, but chat format, message_id semantics, and text constraints are left undefined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action precisely: edit an existing message that the user sent. The phrase 'one of your own sent messages' differentiates it from sending new messages (tg_send) and from editing other entities like topics, chats, or bot messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives. It only implies the message must be an existing one the user sent, but does not mention tg_send for new messages or when tg_edit should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses a conditional behavior (command list only included when the bot is the agent's own bot) and an ownership requirement, which adds value. However, it does not state read-only semantics, auth requirements, or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that front-loads the core function without redundancy. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too sparse to be fully actionable. It does not explain parameter semantics or usage context, though it does note the conditional command list. With no annotations and zero schema coverage, this leaves several gaps for a tool with an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and neither parameter is described in the description. The 'bot' parameter's format (username vs. ID) and the purpose of 'lang_code' are unstated. The description does not compensate for the missing schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a bot's name, about text, description, and command list, scoped to bots the user owns. The verb (get/retrieve) is implied, and it distinguishes from siblings like tg_bot_edit (editing) and tg_chat_info (chat metadata).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving metadata about a bot the user owns, but does not explicitly state when to prefer this over alternatives or exclude cases (e.g., when the bot is not owned). No explicit alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral transparency. It only mentions the default destination directory, but omits critical details like whether files are overwritten, what happens if no media exists, or any filesystem side effects. The tool writes to disk, so more disclosure is expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no redundant information. Front-loaded with the tool's purpose, then the default destination. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no annotations) and presence of an output schema, the description is too thin. It lacks context on expected behaviors like error cases, file handling, or prerequisites. The output schema covers return values, but important usage context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It only hints at the 'dest' parameter via the default path, but does not explain 'chat' or 'message_id' formats, or that 'dest' is optional. The parameter names are self-explanatory, but the description adds little semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Download') and resource ('media attached to one message'), clearly distinguishing from siblings like tg_download_many (plural) and tg_media. The scope 'one message' is explicit and matches the parameter names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: this tool is for downloading media from a single message, contrasting with tg_download_many. However, there is no explicit 'use when' or 'when not to use' guidance, nor mention of alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states what data is accessed (sticker packs, GIFs) but does not disclose whether the operation is read-only, whether it requires special permissions, or what side effects (if any) occur. The phrase 'on the account' hints at account scoping but safety characteristics are left ambiguous.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and uses a clear Arg list. Every piece of information (scope, set, limit) serves a purpose. The opening line is a fragment rather than a full sentence, but the overall structure is efficient and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with an output schema, the description covers the main query dimensions (scope, set, limit) reasonably well. However, it omits guidance on when to use this tool versus sibling tools like tg_send_sticker or tg_media, and it does not describe response formatting or pagination behavior. This is adequate but leaves gaps for an agent unfamiliar with the domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are absent (0% coverage), so the description's Arg explanations are essential. It adds meaning to all three parameters: scope values with concrete meanings, set as a short_name with a t.me/addstickers/<short_name> format, and limit as item count. This compensates well for the schema gap, though it does not mention defaults or type constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource ('Sticker packs and GIFs on the account') and enumerates specific scopes like 'sets', 'set', 'faved', 'recent', 'gifs', which clarifies the retrieval function. However, it lacks an explicit verb like 'list' or 'fetch', and does not directly contrast with siblings like tg_send_sticker, though the resource is distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied through the scope argument: each option describes what it does ('installed packs', 'contents of one pack', 'saved GIFs'), and the note that 'set' requires the `set` parameter provides some conditional guidance. But there are no explicit alternatives or exclusions, and no mention of when to prefer this over related tools like tg_media or tg_download.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden, but it only states the basic action. It does not disclose potential side effects like whether pinning a new chat unpins a previously pinned one, whether multiple chats can be pinned, or any permission requirements. This is a significant gap for an AI agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant words. It front-loads the action and object, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool, the description gives the core purpose, but it lacks critical context such as chat parameter format and behavioral nuances. The presence of an output schema covers return values, but without annotations and with minimal description, the tool is not fully specified for an agent to invoke unboundedly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It implicitly maps 'chat' and 'unpin' to the parameters but provides no details on chat identifier format (e.g., ID, username) or the effect of the unpin flag. The description adds minimal meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Pin') and resource ('a chat') and clearly states the dual functionality ('or unpin it'). It differentiates from sibling tg_pin_message by specifying 'chat' and 'top of the list', making the primary purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for pinning/unpinning a chat but provides no explicit when-to-use vs alternatives or exclusions. It does not mention tg_pin_message or other relevant tools, so the guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must carry behavioral disclosure. It lists the operations but doesn't explain that null values leave fields unchanged, that it's a mutating operation, or any side effects/reversibility. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence lists all operations without redundancy. It is appropriately sized and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter mutation tool, the description lacks crucial guides: null semantics, need for chat/topic_id, and potential conflicts when combining fields. Output schema covers return values, but effective invocation depends on understanding optionality.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description maps each verb to a parameter (rename→title, close→closed, hide→hidden, pin→pinned), adding semantics beyond the schema. However, it doesn't explain the role of chat and topic_id, nor the nullable 'leave unchanged' behavior, so coverage remains incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verbs ('Rename', 'close/reopen', 'hide', 'pin') with resource 'forum topic', clearly identifying the tool's function. It distinguishes from siblings like tg_topic_create (creation) and tg_pin (message pinning).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when/when-not guidance or alternatives are mentioned. The intended use is implied by the action list, but there's no clarification about when to choose this over tg_edit or tg_pin for topic-related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral transparency burden. It discloses the ordering ('newest last') and the semantic bounds for the 'since' parameter (ISO timestamp lower bound), but it does not describe the output structure or what constitutes an 'event' beyond 'incoming messages.' It also doesn't clarify what 'the watcher' is. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: a single purpose sentence followed by a clean 'Args:' section with two bullet-style explanations. No wasted words, information is front-loaded, 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.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter getter with an output schema, the description is mostly sufficient, but it leaves key context unexplained (what 'the watcher' is, what events look like). It also doesn't distinguish itself from siblings like tg_history. Given the complexity is low, this is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description fully explains both parameters: 'limit' as 'how many events' and 'since' as 'ISO timestamp lower bound' with an example. This compensates well for the missing schema descriptions, though the explanations are terse.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'recent incoming messages captured by the watcher, newest last,' which identifies a specific resource (watcher-captured incoming messages) and ordering. It lacks an explicit verb like 'list' or 'get,' and doesn't explicitly contrast with sibling tools, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context ('captured by the watcher') but provides no explicit guidance on when to use this tool versus alternatives like tg_history or tg_mentions. There are no exclusions or alternative tool mentions, so guidance is merely implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosure. It explicitly states that passing cancel_ids cancels scheduled messages, revealing the tool's dual behavior. However, it does not mention consequences such as permanence, whether cancellation requires confirmation, or how invalid IDs are handled. The core mutation is acknowledged but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose. The argument list is compact and easy to scan. The only issue is the initial sentence is a fragment ('Messages scheduled for later in a chat.'), which is slightly awkward, but it does not waste words or obscure meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's two modes (list and cancel), parameter semantics, and the chat identifier format. An output schema exists, so return values need not be described. It lacks usage guidance and edge-case behavior, but for a tool of moderate complexity, the core functionality is adequately covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides clear explanations for all three parameters: chat format ('chat id, @username, exact title or me'), limit ('how many to list'), and cancel_ids ('message ids to cancel instead of listing'). This adds significant meaning beyond the raw schema and fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states that the tool deals with 'Messages scheduled for later in a chat' and that passing cancel_ids cancels them. This clearly indicates it lists and optionally cancels scheduled messages, distinguishing it from siblings like tg_schedule (which likely creates them). The phrasing is slightly fragmented but the intent is understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternative guidance is provided. While the behavior of listing vs. canceling is implied by the presence of cancel_ids, there is no mention of when to use this tool instead of tg_schedule, tg_send, or other messaging tools. The description leaves usage context entirely to the agent's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the action without disclosing effects, permission requirements, or reversibility beyond the unblock flag. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that gets straight to the point. Every word contributes to understanding the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two parameters and an output schema, so the description is mostly adequate. However, it omits details about what value the user parameter expects (e.g., ID, username) and any side effects or restrictions, leaving room for ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds semantic meaning to both parameters: 'user' is the target of the block, and 'unblock=true' toggles to unblocking. This goes beyond the schema's type and default definitions, though it lacks specifics on the expected format of the user identifier.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool blocks a user and can unblock with the 'unblock=true' flag. This is a specific verb+resource action that distinguishes it from sibling tools like tg_mute or tg_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for blocking or unblocking a user but provides no explicit guidance on when to choose this over alternatives. No exclusions or alternative tool references are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It states 'Not recoverable' and explains that revoke=True removes messages for everyone, conveying destructive permanence and audience. However, it omits permission requirements and the exact behavior when revoke=False, leaving minor gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences that pack essential safety and scope information with no filler. The main verb appears first, making it highly scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple three-parameter tool with an output schema, but the description omits revoke=False behavior and permission prerequisites. While core deletion semantics are present, an agent might not know limitations for deleting others' messages or when revoke=False is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the revoke parameter's effect, but chat and message_ids are left to their names with no additional format or usage guidance beyond the schema. The added revoke semantics prevents a lower score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Delete' with a clear resource 'messages' and immediately clarifies the revoke option, which defines deletion scope. It unambiguously distinguishes this from sibling tools like tg_edit or tg_archive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives, nor are there any exclusions or scenarios described. The tool name implies usage, but the description does not explicitly frame when deletion is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It adds useful context like 'as the user', album behavior for multiple paths, voice message conversion, and silent delivery. However, it does not mention permissions, file size limits, or potential 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a one-line purpose followed by a bullet list of parameters. Every sentence adds value and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers core functionality and parameter semantics well, but lacks context about file path formatting, authentication implications of 'as the user', error behavior, or any constraints. It is adequate but leaves notable gaps for a tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the Args list is essential. It provides meaningful semantics for all five parameters: chat as recipient, path as single/album, caption text, voice mode, and silent delivery. This goes well beyond the bare schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Send a local file as the user' with a specific verb and resource. 'Local file' distinguishes this from sending stickers, locations, or remote URLs, and the mention of album/voice modes further clarifies its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like tg_send, tg_send_sticker, or tg_send_location. The description only explains what the tool does, not when it should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The word 'status' implies a read-only operation, and the listed items (signed-in users, alert rules, write permission) provide some behavioral context. However, it does not explicitly state that the operation is side-effect-free, whether data is live, or any error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that front-loads the main purpose. It lists key components without wasting words, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter status tool with an output schema, the description covers the essential scope. It could be improved by mentioning whether this is a real-time health check or a summary, but the current description is adequate for a simple status query given the schema likely documents the return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts zero parameters, so schema coverage is vacuously 100% and the description does not need to explain parameters. The description appropriately omits parameter details, matching the empty input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as reporting daemon and account status, with specific items such as signed-in users, alert rules, and write permission. It distinguishes itself from sibling tools like tg_accounts or tg_alert by presenting a combined status overview, though it lacks an explicit verb like 'get' or 'list'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for checking overall status but does not explicitly state when to prefer this over sibling tools such as tg_accounts, tg_sessions, or tg_rules. No exclusions or alternatives are mentioned; the context of being a general status endpoint is inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It accurately describes what the tool returns (mutual groups/channels) but does not mention side effects, authorization, rate limits, or explicitly state it is read-only. This is a basic level of transparency, not exceptionally detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core function and followed by a practical use-case sentence. Every word earns its place; there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple query tool but lacks parameter details and caveats. The presence of an output schema covers return values, but the overall context is incomplete due to missing parameter semantics and behavioral disclosures that annotations would normally provide.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for its two parameters. The tool description does not explain the 'user' or 'limit' parameters at all, leaving the agent to infer from names and types. Since the description does not compensate for the missing schema descriptions, the semantic guidance is weak.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Groups and channels you and this person are both in.' This specifies the output resource and distinguishes it from sibling tools like tg_chat_info (single chat info) and tg_participants (participants in a chat). The additional use-case note ('where do we overlap', 'placing an unknown contact') reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'Good for "where do we overlap" and for placing an unknown contact.' This tells the agent when to use the tool. However, it does not mention alternatives or when not to use it, 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It describes the output content (pinned chats, exclusions, rules) but does not explicitly state that this is a read-only operation or mention any side effects, permissions, or limitations. For a simple read tool, the lack of such statements is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long and front-loaded with the main purpose in the first line. The second sentence adds useful detail about the folder contents without any redundant or fluffy language. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the zero-parameter schema and the presence of an output schema, the description is sufficiently complete. It explains what folders are and what data is included, leaving return-format details to the output schema. No further context is needed for an agent to understand this tool's role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema fully covers everything (100% coverage). Per the rubric, zero parameters merits a baseline of 4. The description adds no parameter-specific semantics because no parameters exist, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as 'Telegram folders (chat filters)' and states what it provides: which chats each folder holds. It distinguishes from siblings like tg_folder_edit (which edits folders) and tg_dialogs (which lists chats). However, it lacks an explicit verb like 'list' or 'get', so it's not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for reading folder structures and their chat memberships, which gives context for when to use it. It does not explicitly mention when not to use it or name alternatives like tg_folder_edit for modifications. Usage guidance is thus implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden; it does disclose return fields and notes that phone is included only when visible, which is useful. However, it does not mention permissions, rate limits, pagination behavior, or failure modes for large groups/private chats.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a concise opening summary, a useful bullet-style list of returned fields, and a clean Args block. Each sentence adds value, though the field enumeration makes it slightly longer than strictly necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with three parameters and an output schema, the description provides adequate coverage: it names all parameters with semantics and summarizes the result contents. It lacks some operational context such as permissions or error cases, but this is not critical for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are absent (0% coverage), and the Args section fully compensates by explaining each parameter: chat accepts id, @username, or exact title; limit controls member count; query filters by name or username. This is precisely the semantic enrichment needed beyond the schema's bare type declarations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly indicates the tool returns members of a group/channel and enumerates key fields (username, direct chat link, phone, role, last-seen, flags), which distinguishes it from related tools like tg_contacts or tg_chat_info. However, it lacks an explicit verb like 'List' or 'Get', relying on a noun phrase to convey the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving members when you have a chat identifier, but it does not explicitly state when to prefer this over alternatives such as tg_contacts or tg_chat_info, nor when not to use it. No exclusion or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the burden of behavioral disclosure. It does disclose the key precondition that topics must be enabled in the supergroup, which is valuable. However, it does not mention permission requirements, side effects, or behavior if the precondition is not met.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the action and resource. Every word serves a purpose, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential purpose and a key constraint, but lacks parameter explanations and usage alternatives. For a tool with three parameters and no annotations, an agent would need more details about chat identifiers and icon emoji format to invoke it correctly. The presence of an output schema reduces the need to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it does not explain the meaning or expected format of 'chat', 'title', or 'icon_emoji_id'. 'Title' is somewhat implied by 'forum topic', but 'chat' and 'icon_emoji_id' are left entirely to their minimal schema names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' and identifies the resource 'forum topic' with the scope 'in a supergroup that has topics enabled'. This clearly distinguishes it from siblings like tg_topic_edit and tg_topics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: only in a supergroup that has topics enabled. This implies the prerequisite but does not explicitly mention alternatives or when not to use it, though the verb 'create' differentiates it from edit tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It discloses the channel (agent's own bot) and that it does not operate in chats, but it does not mention prerequisites (e.g., whether the user must have an active chat with the bot), delivery semantics, or potential side effects. This is minimal but acceptable for a simple notification tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is clear, front-loaded, and free of extraneous information. Every word contributes to distinguishing the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (one parameter, no nested objects, output schema present), the description is largely sufficient for an agent to use it correctly. However, it omits any guidance on prerequisites, failure behavior, or when to prefer this over similar sibling tools, leaving some gaps for a tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has a single 'text' string parameter with 0% schema description coverage. The description implies the text is the notification content by mentioning 'a notification', but it does not explicitly clarify the parameter's role. The meaning is easily inferred, but the description adds minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Send') and resource ('a notification through the agent's own bot'), clearly stating what the tool does. The parenthetical '(not their chats)' explicitly distinguishes this from sibling tools that send messages to chats (e.g., tg_send, tg_message), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for when to use this tool: to send a notification via the agent's bot, with an explicit exclusion of chats. While it doesn't name alternative tools, the 'not their chats' gives a clear when-not, which is more than implied usage but less than explicitly naming alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the dual action (pin or unpin) and clarifies that it does not affect chat order. However, it omits other behavioral traits such as whether pinning replaces an existing pinned message, whether the 'notify' parameter sends a service message, or any permission requirements. The basic action is clear, but deeper behavioral context is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the action, and contains no filler. Every phrase is purposeful: the first sentence states the operation, the second disambiguates from a sibling. This is exemplary conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no annotations, and no schema descriptions, the description is too sparse to provide complete context. It explains the core purpose and differentiates from tg_pin, but it does not address the 'notify' parameter semantics or any operational side effects. While an output schema exists, the missing parameter guidance makes the description incomplete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation. The description implicitly maps 'chat' and 'message_id' via 'one message inside a chat' and mentions the 'unpin' boolean through 'or unpin', but it does not explain the 'notify' parameter at all. The description adds some meaning but leaves a significant gap for a four-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Pin (or unpin) one message inside a chat.' It specifies the resource (a message) and scope (inside a chat), and explicitly distinguishes itself from the sibling tool tg_pin, which pins the entire chat. This leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts this tool with tg_pin ('This is different from tg_pin, which pins the whole chat to the top of your dialog list.'), thereby telling the agent when to use this tool (pinning a specific message) and when not to use it (pinning the whole chat instead). This is exactly the level of guidance expected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the straightforward mutating behavior ('invite people') and the destructive 'revoke' flag, which revokes the old link and issues a new one. However, it does not disclose any permissions required, side effects such as user notifications, or irreversibility of revoking a link. With no annotations, this leaves the agent guessing about safety and consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact two-line summary followed by four bullet-like argument definitions. Every sentence adds information and there is no filler. It is front-loaded with the main purpose, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so the lack of a return description is acceptable. The description covers all four parameters and the two functional modes (inviting and link handling). However, it does not clarify whether users is required when obtaining a link, nor whether revoke automatically returns a new link, leaving a small ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The Args section defines each parameter in plain language: chat is 'the group or channel', users is 'who to add', link will 'also return the primary invite link', and revoke will 'revoke the old link and issue a new one'. This compensates for the empty schema descriptions, but it does not go deeper into accepted user formats or whether users is optional when obtaining a link, so a bit more context would be beneficial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Invite people to a chat and/or get its invite link,' which clearly identifies the primary action (invite) and resource (chat), and adds a secondary capability (getting the invite link). This distinguishes it from sibling tools like tg_leave or tg_participants, which target different chat operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but does not explicitly state when to use it instead of related tools such as tg_participants or tg_create_group. No exclusions or alternative tool names are mentioned. Usage is implied by the verb 'Invite,' but clear guidelines are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It clearly discloses the irreversible consequence of delete=true and advises asking first, but it does not mention other behavioral traits such as permissions or whether leaving is reversible in group/channel contexts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two sentences, front-loaded with the action and adding a necessary warning. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple leave operation, the description covers the core purpose and the destructive edge case. An output schema exists, so return-value documentation is unnecessary. It lacks explicit alternative-tool guidance but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaningful semantics: delete=true erases the conversation on your side and is not recoverable, and chat implies group/channel/private chat. This compensates for the missing schema-level parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'leave' with explicit resources (group/channel), and distinguishes this tool from siblings like tg_delete by focusing on leaving rather than deleting content. The private-chat delete nuance adds further clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives contextual guidance for private chats ('ask first' when delete=true) but does not explicitly state when to use this tool versus alternatives like tg_delete or tg_edit. Usage context is implied rather than fully specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the return content (reactions, buttons, read counts, context, replies), but does not disclose potential side effects, permission requirements, or rate limiting. It is a read operation, but this is not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence summary followed by a clear Args list. No fluff, every line serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 params, no annotations) and presence of an output schema, the description covers the essentials. It explains parameters and scope, though it could mention default behavior (already in schema) or limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions (0% coverage), so the description's Args block adds value by explaining each parameter: chat with examples, message_id purpose, context and replies meaning. It could be more detailed on formats, but it compensates well for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns a single message in full, including reactions, inline buttons, read count, and optional context/replies. The verb 'inspect' is implied, and it distinguishes itself from siblings by focusing on one message with rich detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it—when you need full details of a single message—but does not explicitly mention alternatives or exclusions. It lacks 'use this instead of X' guidance, which is important given many siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the default behavior (indefinite mute) and the unmute option, implying reversibility. However, it does not explain what muting actually does (e.g., silences notifications, hides the chat) or whether any permissions are required. This is some context, but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that front-loads the action and key details. No wasted words; every word contributes to understanding the tool's purpose and options.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with an output schema (so return values need not be described), the description covers the main behavior, default, and unmute option. It lacks edge-case explanations (e.g., hours=0 or negative) but is sufficiently complete for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains 'N hours' and 'default: indefinitely' (which maps to the null default of the 'hours' parameter), and 'or unmute it' maps to the 'unmute' boolean. The 'chat' parameter is not explicitly described but is obvious from the name and the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Mute a chat for N hours (default: indefinitely), or unmute it.' It uses specific verbs ('mute', 'unmute') and a specific resource ('chat'), and it distinguishes from siblings like tg_alert, tg_notify, and tg_block by focusing on the mute/unmute action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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 want to mute or unmute a chat), but it does not explicitly state alternatives, exclusions, or prerequisites. There is no mention of when to prefer this over tg_alert or tg_notify, so guidance is minimal but not absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the non-obvious trait that omitting `emoji` removes the reaction, which goes beyond the basic action. However, it does not mention whether existing reactions are replaced or any permission requirements, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loaded with the primary action, and every word adds value. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the description covers its core functionality and the key 'remove' use case. However, it omits the `big` parameter's purpose and any context about prerequisites or side effects, making it adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter explanations. It only explains the `emoji` parameter's special behavior (null removes reaction), while `chat` and `message_id` are left to name inference and `big` remains unexplained. This is insufficient given zero schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action 'React to a message with an emoji' and identifies the resource (message). It also distinguishes itself from siblings like tg_send or tg_edit by focusing on the reaction feature, and it adds the unique removal behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this tool to add or remove reactions on a message. It includes a specific usage instruction ('Omit emoji to remove your reaction') but does not explicitly name alternatives or exclusions, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since there are no annotations, the description carries the full burden of behavioral disclosure. It reveals the auth requirement and the kind of events returned. It stops short of mentioning whether the operation is read-only, the ordering, or the behavior with insufficient permissions, but the core behavioral traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: a one-sentence lead followed by four one-line parameter explanations. Every sentence carries useful information, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, there is no need to describe return values in the text. The description covers purpose, auth requirement, and all parameters adequately for a straightforward log-retrieval tool. It lacks examples or edge-case details, but these are not essential for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description fully compensates by giving all four parameters ('chat', 'limit', 'query', 'admins') short, meaningful explanations that go beyond the raw type information. This makes the parameters easy to understand.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: retrieving the admin log of a group or channel, with examples of event types (deleted, banned, promoted, renamed) and time. It lacks an explicit verb like 'get' or 'list', but the meaning is unambiguous and it is distinct from sibling tools like tg_events or tg_activity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite (needs admin rights) and implies the tool is for inspecting admin actions. However, it does not explicitly state when to prefer this tool over alternatives such as tg_events or tg_activity, nor does it mention any exclusions or fallback guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses the private nature of the note (only owner sees, not sent anywhere). However, it doesn't mention potential side effects like deletion irreversibility, overwriting existing contacts, or permission requirements, leaving notable behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with a one-sentence summary followed by a structured Args list. Every sentence adds value; there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With six parameters and three operations, the description is mostly adequate but leaves ambiguities: 'user' is not fully explained, and there are no notes about edge cases like conflicting parameters or behavior when adding an existing contact. The presence of an output schema lessens the burden for return values, but overall the description is just minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It effectively explains the role of each parameter: phone, name, last_name for adding; user for delete/note; delete flag; and note with privacy semantics. It adds meaning beyond the schema, though it lacks format details (e.g., phone format, user ID vs username) and combination constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states three specific operations: add a contact by phone number, delete one, or keep a private note. This distinctively identifies the tool's purpose and differentiates it from sibling tools like tg_contacts (listing) and generic tg_edit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The Args section explicitly defines which parameters are used for adding, deleting, or noting, providing clear operational usage context. It does not explicitly name alternatives or exclusions, but the usage patterns are unambiguous enough for an agent to select this tool among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses key behaviors: nothing leaves the account, the draft survives across devices, and it is not sent until the user presses send. It also explains the clear=true behavior. It does not cover error cases or permissions, but the core safety profile is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, efficiently front-loaded. The first sentence states the action, the second gives usage context, and the third clarifies a parameter. No redundant words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description covers main purpose, usage scenario, and a key parameter. Missing details on reply_to and error behavior, but the core functionality is complete for an agent to decide when to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only explains the 'clear' parameter ('Pass clear=true to wipe the draft'). 'chat' and 'text' are implied by context, but 'reply_to' is completely unexplained. This leaves a significant gap in parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Save a draft in a chat instead of sending it.' This distinguishes it from sibling tools like tg_send or tg_schedule, and explicitly mentions the resource (chat) and the action (save draft). The phrase 'instead of sending' directly contrasts with send tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use: 'This is the right tool when a message needs the user's eyes first: nothing leaves the account, and it survives across devices.' It implies when not to use (when immediate sending is desired) but does not name specific alternatives like tg_send. Clear context, but no explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains that only unread mentions/reactions are returned and clarifies the 'reactions' mode, but does not state whether fetching this data marks items as read or has other side effects. With no annotations provided, this missing side-effect disclosure is a notable gap, though the tool appears to be read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, leading with the purpose and following with a clean Args list. Every sentence adds value and there is no redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two optional parameters and an output schema, the description covers the essential behavior and parameter semantics. Minor gaps include not explicitly stating the scope (all chats) or whether results are ordered, but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description fully explains both parameters in depth: 'limit' is defined as 'how many to return' and 'kind' has explicit meanings for 'mentions' and 'reactions' with default behavior. Since the schema contains no descriptions, this completely compensates for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose as retrieving unread messages that mention the user or unread reactions to their messages. It distinguishes mentions from reactions, but lacks an explicit verb like 'get' or 'list', making it slightly less direct than ideal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by explaining the two 'kind' options and their meanings, which implicitly tells the user when to use each mode. However, it does not explicitly discuss alternatives or exclusions relative to other tools such as tg_unread or tg_activity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It explains how to select stickers via scope, index, or emoji, but does not disclose side effects, permissions, error behavior, or whether the operation is irreversible. Basic send functionality is transparent, but deeper behavioral details are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single purpose line followed by a clean, bulleted list of parameters. It is concise, with no wasted words, and front-loads the core action before detailing parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a send tool with an output schema present, the description covers the essential purpose and all parameters. It lacks contextual details like prerequisites or common error cases, but given the relative simplicity of sending stickers/GIFs and the existence of an output schema, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, yet the description fully explains every parameter: chat, scope, set, index, emoji, and reply_to. It adds meaningful semantics like scope options, the dependency of set on scope, and referencing tg_stickers for index numbering, far exceeding schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Send a sticker or a saved GIF.' This specific verb+resource is distinct from sibling tools like tg_send_file or tg_send_location, making the purpose immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying the tool's purpose, but it does not explicitly state when to use this tool over alternatives like tg_send or tg_send_file. It lacks explicit when-not guidance or mention of sibling tools, so the usage context is only inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by disclosing that pressing a button is an action taken as the user and requires confirmation. It also indicates the button matching is 'exact-ish' and supports index selection, giving useful behavioral nuance beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences deliver all essential information without fluff. The first defines behavior and modes; the second adds a crucial safety caveat. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's two modes, selection criteria, and safety requirement, which is adequate for a Telegram inline-keyboard tool with an output schema. Minor gaps like index base and chat/message_id format exist, but the core behavior is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful details for the `button` parameter (omit to list, provide to press, matching by text or index), but it does not explain `chat` or `message_id` beyond their schema names/types. With 0% schema description coverage, more parameter guidance would be expected.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly identifies the resource (inline keyboard under a bot's message) and the two actions: listing buttons without `button` and pressing one with `button`. This clearly distinguishes the tool from siblings like tg_react or tg_send by focusing specifically on inline keyboard interaction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides direct usage instructions: call without `button` to inspect buttons, with `button` to press one, and selection can be by text or index. It also gives a critical guideline about confirming before clicking on the user's behalf, though it does not name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It adds useful behavioral details such as 'quiz_answer' making it a quiz and 'anonymous: false shows who voted for what', but it does not disclose return values, permissions, or failure modes, which leaves some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one purpose sentence plus a clean list of arguments. Every line earns its place, and it is front-loaded with the core action and constraint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter tool with no annotations, the description covers all parameters and includes a key platform limitation. An output schema exists, so return values are not required. It lacks prerequisites like how to obtain a chat ID, but that is likely handled by sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning to each parameter—e.g., 'multiple: allow several answers', 'quiz_answer: index of the correct option'—beyond the bare schema titles. It does not go into deep format details but covers the essentials.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Post a poll (2-10 options)' which is a specific verb and resource. It is easily distinguished from sibling tools like tg_send or tg_message, and the parenthetical adds a key constraint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clarifies that polls are only for groups or channels by saying 'Telegram refuses polls in private chats' and labeling chat as 'group or channel'. This provides a clear when-not context, though it does not explicitly name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of transparency. It mentions using Telegram's own translator and a max of 20 message IDs, but does not disclose whether this operation modifies anything, the return format, or edge cases like what happens when both text and message_ids are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and well-structured: an action-first first sentence followed by a clean args list. Every line adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core function and parameter semantics adequately for a translation tool. It lacks explicit guidance on parameter interactions (e.g., precedence if both text and message_ids are provided), but the presence of an output schema reduces the need to describe return values. Overall, it is sufficiently complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining all four parameters: to_lang with examples, chat as the location of messages, message_ids with a max limit, and text as an alternative to message translation. This is a clear upgrade over the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Translate messages (or any text) with Telegram's own translator.' This distinguishes it from sibling tools like tg_transcribe (audio transcription) and tg_summarize (summarization).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by stating it translates messages or arbitrary text. While it does not explicitly mention alternatives or exclusions, the absence of any other translation tool among siblings makes the usage context sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It adds useful context about multi-account support and the selection mechanism, but it doesn't disclose edge cases (e.g., what happens if no account is signed in) or any side effects. Since it's a read-only query tool, this is acceptable but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary purpose. The second paragraph adds necessary context about account selection without redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has no parameters and an output schema exists, the description is sufficiently complete. It explains the account model and how this tool fits with siblings, providing enough information for an agent to know when and why to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline is 4. The description correctly avoids parameter information since none exist, and the schema already confirms this.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: showing which Telegram accounts the daemon holds and which one is currently active for calls. It distinguishes itself from the sibling tool tg_account_use by explaining that tg_accounts is about querying account state, not switching accounts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it explains that multiple accounts can be signed in and that every other tool operates on the account selected via tg_account_use. This implies when to use tg_accounts (to view accounts and current selection) and points to an alternative for selection, though it doesn't explicitly say 'use this when you need to know the active account'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the key behavior of creating a supergroup/channel and optionally inviting users, and clarifies 'kind' values. Yet it does not mention permissions, reversibility, or other side effects, missing important context for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a one-sentence purpose followed by a clean Args list. No wasted words, and every sentence contributes meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for invoking the tool: required title, optional users, and kind/about are all addressed. Since an output schema exists, return values need no explanation. The only gap is lack of explicit guidance on when not to use this tool, which is minor given the clear purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It fully does: each parameter is explained with added meaning—title as name, users with accepted formats, kind with values, and about as description. This goes well beyond the schema's bare types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create a supergroup or a channel' and optionally inviting people, using a specific verb and resource. It distinguishes itself from sibling tools like tg_chat_edit and tg_invite by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this to create a new chat and optionally add users immediately. However, it does not explicitly mention alternatives like tg_invite for existing chats or tg_chat_edit for modifications, so there are no exclusions or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behaviors itself. It states the 50-item limit and the default download directory, which is helpful. However, it omits details like file overwriting, permissions, error handling, or side effects on the filesystem, leaving some operational uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise: a two-sentence summary plus a compact Args block. Every sentence contributes meaning, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple batch download tool, the description covers purpose, parameters, a key constraint (max 50), and the source of IDs. It omits edge-case behaviors, but the presence of an output schema likely covers return values, so this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero descriptions, so the description compensates fully. The Args section clearly explains each parameter: chat, message_ids, and dest, including the default path for dest. This adds meaning beyond the schema's bare type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's function: downloading multiple attachments at once, with a specific maximum of 50. It also directs users to retrieve IDs from tg_media, which distinguishes it from the sibling tool tg_download for single-file downloads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides practical context: batch downloads with a max of 50, and instructs users to obtain message IDs from tg_media. While it doesn't explicitly mention preferring tg_download for single files, the phrasing 'several at once' implies the appropriate use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It implies a read-only operation by stating tags and counts, but does not explicitly mention lack of side effects or any auth/rate-limit context. It does add the useful behavior of producing values consumable by tg_search.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the core purpose and a practical follow-up. No wasted words or redundant schema repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description is fully complete: it explains what the tool returns and how to consume the results. The output schema covers return structure, so no further detail is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline is 4. The description adds no parameter-specific info because none is needed; it provides context about how the returned tag values are used.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists tags used in Saved Messages with message counts. This is a specific resource (Saved Messages tags) and scope, effectively distinguishing it from siblings like tg_search or tg_drafts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit usage path: feed a title back into tg_search(chat="me", tag=...). This implies when to use the tool (to discover tags) and the next step, though it does not explicitly state alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explains that each chat indicates archiving status and the semantics of the archived parameter, but it omits any statement about side effects—most notably whether fetching unread messages marks them as read. This is a significant gap for a tool dealing with unread state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with a clear summary, followed by a well-organized argument list. No redundant text; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the output schema exists, so the description covers core invocation details: what it returns, how to limit results, and the archived filter. The only notable omission is the potential side effect on read status, which prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only titles with 0% description coverage, yet the description comprehensively explains all three parameters (limit_chats, per_chat, archived) with clear semantics for null/false/true. This fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all unread messages grouped by chat with the latest incoming messages, using a specific verb and resource. It explicitly frames the use case for 'what did I miss' questions, distinguishing it from walking through chats one by one and from sibling tools like tg_history or tg_mentions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool for 'what did I miss' questions instead of walking chats one by one, providing a clear use case and an alternative. However, it does not explicitly name when not to use it or reference other sibling tools as substitutes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility. It explicitly discloses both destructive behaviors: dropping the cache index and optionally deleting everything in data/downloads. However, it omits details on reversibility or potential side effects, which is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence: primary action, usage context in parentheses, and optional action. No redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description covers essential behavior and usage context. It does not detail return values (unnecessary) or prerequisites, which are likely common across siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining the 'downloads' parameter's effect ('optionally delete everything in data/downloads'). This adds meaning beyond the schema's type/default, though it could explicitly state true/false mapping.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's primary action ('Drop the cached chat-title index') and its optional secondary action ('delete everything in data/downloads'), with a specific usage context ('use after chats are renamed'). This definitively distinguishes it from sibling tools like tg_download or tg_delete by focusing on cache management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies an explicit trigger for use ('after chats are renamed'), giving clear context. It does not mention alternatives or when-not-to-use scenarios, but for a singular cache-clearing tool, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description shoulders the transparency burden. It discloses behavioral details: birthdays are 'sorted by date', top is 'ranked by Telegram itself', and it clarifies the query limitation. This gives the agent a good sense of what the tool returns without needing to call it. It doesn't mention network/permission concerns, but for a contacts lookup this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a concise purpose sentence, then cleanly structured as an args list with one line per parameter, using consistent formatting for kind values. Every sentence adds value; no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return formatting is already covered. The description covers all parameter semantics and the distinct modes, making the tool's behavior fully understandable for an agent. Given the simplicity of a contacts list, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully documents all three parameters: query (filter by name or username, constrained to kind='all'), limit (how many rows), and kind (enumeration of five values with explanations). This is a model of parameter documentation, adding meaning well beyond the schema's bare property definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Your contacts, or a slice of them', clearly identifying the resource and implying retrieval. The detailed kind list (all, birthdays, top, online, blocked) further specifies the scope and distinguishes the tool's multiple modes. However, no explicit verb like 'list' or 'get' is used, making it slightly less direct than ideal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use each kind, e.g., birthdays 'answers whose birthday is coming up' and top shows 'people, groups and channels this account interacts with most'. It also notes query only applies to kind='all', which is a useful exclusion. It doesn't name alternative sibling tools, but the guidance is sufficient for most use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It explicitly states that delete only removes the folder and leaves chats intact, and that omitted arguments preserve existing settings. It also details the rule checkboxes. It does not mention auth or error behavior, but covers the main safety-relevant traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-line summary, a crucial safety note about non-destructive behavior, then a clean Args list. Each parameter line is informative and not redundant; it is somewhat long but appropriate for 9 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters and no annotations, the description is quite complete: it covers purpose, safety, and all parameter meanings. It does not explain return values, but an output schema exists. It also does not explicitly discuss operation combinations (e.g., create+add), but the 'anything not passed' statement implies composability. Overall, it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero descriptions (0% coverage), so the description must compensate, and it does thoroughly. All 9 parameters are explained with added detail like 'max 12 characters' for create, 'from tg_folders' for folder, and the specific rule names, providing far more meaning than the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create, delete, rename and fill Telegram folders,' a specific verb-resource combination that clearly states the tool's scope. This distinguishes it from sibling tools like tg_folders (likely listing) and tg_topic_edit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context on how to reference existing folders ('from tg_folders') and explains that unspecified arguments are left untouched, which is important for safe combination with other operations. It does not explicitly name alternative tools when not to use this one, 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that kicking and banning are visible to the whole chat, clarifies that approve/decline answer pending join requests, and notes the admin requirement. This gives a solid understanding of side effects and preconditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the primary verb and resource, followed by functional details and a caution. Every sentence adds necessary information with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It covers the tool's purpose, admin-only condition, visible side effects, and the meaning of approve/decline. With an output schema present, return values are already specified. Minor omission: no explicit mention of identifier formats for chat/user, though the names are self-explanatory.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds the list of valid action values (kick, ban, unban, promote, demote, approve, decline), which is absent from the schema's 0% description coverage. However, it does not explain acceptable formats for chat/user identifiers or any constraints, leaving a partial gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource ('Moderate a group member') and enumerates specific actions (kick, ban, unban, promote, demote, approve, decline). This distinguishes it from sibling tools like tg_block or tg_message, which have different scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states 'Only for chats where the user is an admin' and advises to 'Confirm before using', providing clear context for when to use the tool. It does not name alternative tools or exclusions, but the conditions are specific enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It explicitly states the tool does not open or join anything, and explains how non-Telegram URLs are handled ('reported as external') with a safety rule about not fetching them based on message content. This goes beyond the bare 'resolve' verb and gives meaningful security/behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences deliver purpose, scope, and a critical safety instruction with zero filler. The most important information is front-loaded, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (multiple link types and varied output), the description covers the essential behaviors: what it resolves, what it returns for each link type (title, member count, message, etc.), and external URL handling. An output schema exists, so detailed return formatting is not required here. It is sufficiently complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has a single 'link' parameter with zero description coverage, so the description must compensate. It does so by listing the accepted link formats (t.me/username, t.me/+invitehash, etc.), which tells the user the expected input structure. This adds semantic value that the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb phrase 'Say what a Telegram link points at' and clearly distinguishes this from sibling tools by stating it does so 'without opening or joining anything.' It enumerates the exact link types handled (t.me/username, t.me/+invitehash, joinchat, t.me/c/..., t.me/user/<id>, addstickers), leaving no ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it resolves Telegram links without side effects, and explicitly warns against fetching external URLs unless the user asked for it. It does not name specific sibling tools as alternatives, but the 'without opening or joining' and 'fetch with a web tool only if the user asked' guidance effectively tells when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does a good job by detailing what data the tool returns (counts, unread, pinned, archived, folders) and how the 'sample' argument affects output. It does not explicitly state read-only safety, but the meaning of 'map' strongly implies a non-mutating overview.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: two sentences plus a single args line. It front-loads the core purpose in the first line, provides usage context in the second, and explains the parameter without any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a single-parameter, account-wide overview with an output schema, and the description covers what data is returned and when to use it. It is complete enough for an agent to select and invoke the tool correctly; edge cases like pagination or folder depth are not mentioned, but the output schema should handle return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'sample' has 0% schema description coverage, so the description must compensate. It does so by explaining 'also include this many example chats from the main list and archive,' adding real meaning beyond the type/default already in the schema. It does not specify allowed ranges or behavior for negative values, but it is sufficient for standard use.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Map of the whole account in one call' and then enumerates specific data categories: counts by type, unread, pinned, archive, and folders. It also says 'Start here when asked about the shape of the account rather than about one conversation,' which clearly separates it from per-conversation sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit when-to-use instruction: 'Start here when asked about the shape of the account.' It also provides a clear when-not ('rather than about one conversation'), though it does not name a specific alternative sibling tool such as tg_dialogs or tg_chat_info.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the switch is session-only and does not affect other clients or the watcher. This is good contextual transparency, though it could mention error behavior or default reset beyond the 'main' hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary behavior, and no wasted words. The second sentence adds necessary scope clarification without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter setter with an output schema, the description is complete: it explains the effect, persistence, and exclusions. The session scope is clearly defined, and the 'main' default covers the common use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does by giving a concrete example ('main' for the default account), adding meaning beyond the raw schema property. It does not enumerate all possible account values, but the tool name and context imply they are account identifiers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: pointing every following tool call at a specified account. It effectively distinguishes itself from sibling tools by being a session-scoped context setter, with a clear resource (the active account).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies when to use (before making tool calls that should target a specific account) and when not (the background watcher is unaffected). However, it does not explicitly name alternatives or provide exclusions beyond the watcher note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It adds important behavioral details: slowmode is in seconds and only for supergroups, forum mode turns a supergroup into a forum, photo must be a local image file, and permissions keys are listed. It does not mention reversibility or potential errors, but it provides substantial context beyond the raw schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a concise purpose sentence followed by a clear argument list. Every sentence adds value, and the permissions key list is useful despite its length. There is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all parameters and key constraints, but it does not explicitly state that only provided fields are updated or how different chat types (channel vs supergroup) affect permission handling. Given the tool's complexity and lack of annotations, this is a minor gap; the description is still highly useful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description fully compensates. Every parameter is explained with its meaning, units, or keys: chat identifies the group/channel, title is the new name, about is the new description, photo is the avatar file, slowmode includes units and a way to disable, permissions has an example and key enumeration, and forum explains its effect. This is exemplary.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it changes a group's or channel's title, description, photo, slow mode, permissions, and forum mode. The verb 'change' is specific, the resource is named, and the list of editable fields distinguishes it from sibling tools like tg_topic_edit or tg_edit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on what can be edited (chat settings) and even includes constraints like slowmode being supergroups-only. However, it does not explicitly mention when to use this tool versus alternatives such as tg_topic_edit or tg_edit, so it falls short of the highest score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and explains filter semantics, folder behavior, and output characteristics like recency, unread counts, and links. It doesn't mention pagination or a read-only guarantee, but for a list operation the behavior is well described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-organized: a single-sentence summary followed by a clean parameter list. Every line serves a purpose, with no redundant or vague phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all parameter semantics and gives a key behavioral insight about the account's archiving habits. Output schema exists, so return format is likely specified there. Minor missing details like pagination and link format hold it back from a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description thoroughly documents all five parameters with concrete meanings and nuanced tips (e.g., archived null behavior, kind values). This fully compensates for the schema gaps and adds practical value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List chats (most recent first) with unread counts and links', which clearly states the action, resource, and key output features. This distinguishes it from sibling tools like tg_chat_info (single chat details) and tg_unread (unread messages only).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides practical usage guidance, especially for the `archived` parameter ('pass null when searching for a chat rather than browsing the main list') and `kind` ('answers "what groups am I in"'). Doesn't explicitly name alternative tools or exclude use cases, but gives clear context for effective use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the burden of behavioral disclosure. It does disclose a batch limit of 'up to 25' chats and that search is 'applied to every chat,' which is useful context. However, it does not mention error handling, behavior on invalid chat IDs, or whether the operation is purely read-only until assumed from the verb 'read.' This lacks depth for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise, using two short sentences to convey purpose and usage, followed by a compact bulleted list of parameters. Every sentence earns its place and there is no redundant or verbose language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage, alternatives, and all parameter semantics, which is strong for a batch read tool. The output schema likely documents return structure, so its absence in the description is acceptable. Minor gaps remain around failure modes and edge cases, but the overall context is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite the schema having 0% description coverage, the description fully explains all three parameters: chats can be 'chat ids, @usernames or exact titles,' limit is 'messages per chat,' and search filters for 'only messages containing this text, applied to every chat.' This adds essential meaning beyond the raw schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads multiple chats in one call, specifying 'Read several chats in one call (up to 25).' It also distinguishes from the sibling tool tg_history by saying 'Use this instead of calling tg_history repeatedly,' making the tool's unique value explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use this instead of calling tg_history repeatedly when comparing or summarising multiple conversations.' This names the alternative tool and defines the exact condition for use, leaving no ambiguity about when to choose this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses a non-obvious behavioral trait ('delivers even if this machine is off') and explains timezone handling for bare ISO times. This adds meaningful context beyond the schema, though it doesn't cover error handling or side effects beyond sending.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, starts with a clear one-liner, and then lists arguments in a structured format. Every sentence adds value, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema and four parameters, all well-covered. The description gives essential scheduling context and timezone behavior, making it complete for typical use. It omits optional details like cancellation or delivery guarantees, but those are not critical for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only names and types; the description fully compensates with clear explanations for each parameter. 'when' gets format examples and a timezone note, while 'reply_to' is defined as a message id. This significantly improves parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Send a message later,' a specific verb and resource that clearly distinguishes it from immediate-send siblings like tg_send. The added detail 'Telegram delivers it even if this machine is off' further clarifies the scheduling behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for delayed delivery and gives concrete time format examples, which serves as guidance. It does not explicitly contrast with alternatives like tg_send, but the context is clear enough that an agent would know not to use it for immediate sends.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses an important constraint: `commands` can only be set for this agent's own bot due to Telegram's token requirement. It also implies an ownership prerequisite by saying 'a bot you own'. However, it does not mention other behavioral aspects like rate limits or reversibility, but for a simple edit tool this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by a necessary clarification about commands. Every sentence provides value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, 1 required, and an output schema, the description covers the main purpose and key constraints thoroughly. It omits `lang_code` details but the output schema and obvious parameter names reduce the risk. The command restriction is a valuable addition that makes the tool's behavior predictable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the meaning of several parameters: display name (name), 'what can this bot do' text (about), description, and the exact format of `commands` as a list of {"command", "description"}. It does not explain `lang_code` or `bot`, though `bot` is self-evident and `lang_code` is minor. Overall, it adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool edits a bot you own, listing specific editable fields (display name, 'what can this bot do' text, description). This distinguishes it from generic sibling tools like tg_edit and tg_bot_info by specifying the resource (bots) and ownership scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool (for editing a bot you own) and provides a when-not/alternative: the `commands` field can only be set for the agent's own bot because Telegram requires the bot's token, and for other bots users should use @BotFather. This gives clear context and an alternative for a specific case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosure. It clearly indicates a read-only operation via 'Read messages' and explains ordering (oldest to newest) and filtering behaviors. It does not explicitly state 'does not modify anything,' but the verb choice makes this apparent, and it adds useful detail on pagination and filters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact docstring with a one-sentence summary followed by a bulleted argument list. Each line adds value, with no fluff or repetition. The purpose is front-loaded, 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.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having six parameters, no annotations, and only an output schema, the description covers all essential aspects: purpose, ordering, pagination, filtering, and chat identification. It is complete enough for an agent to invoke the tool correctly without needing additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the sole source of parameter meaning. It thoroughly explains every parameter: chat accepts multiple formats (@username, t.me link, etc.), limit sets count, before_id enables pagination, from_user filters by user, search filters by text, and topic scopes to a forum topic. This substantially exceeds what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Read messages from one chat, oldest to newest,' which specifies the action, resource, and ordering. This clearly distinguishes it from siblings like tg_search (which searches across chats) and tg_mentions (which focuses on mentions), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it reads messages from a single chat with options for pagination, filtering, and topics. However, it does not explicitly mention alternatives or state when not to use this tool, so it lacks explicit exclusions but still gives strong contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description takes on the full burden. It discloses the core behavior: the unread=true flip and the mention badge clearing. It also explains the 'reminder' purpose. It does not mention error handling, permissions, or idempotency, but for a simple state toggle, the disclosed behavior is sufficient for an agent to predict outcomes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the main purpose. The Args list is clearly structured and each line conveys useful semantics without redundancy. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple state-changing tool with an output schema, the description covers the purpose, all parameters, and the intended use case for the unread option. There are no critical gaps that would prevent an agent from selecting and invoking the tool correctly, given the schema provides required-parameter and default information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters are explained in plain language, adding significant meaning beyond the bare schema. 'chat' accepts a range of identifier formats; 'unread' is clarified as a flip that shows the chat as unread again; 'clear_mentions' specifies the badge behavior. This fully compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence, 'Mark a chat as read, or put the unread mark back on it,' clearly identifies the verb (mark), resource (chat), and the dual read/unread behavior. This specific scope distinguishes it from sibling tools like tg_unread, which likely lists unread chats rather than modifying read state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use each operation: marking read for normal consumption, and using unread=true as a reminder mechanism. However, it does not explicitly mention alternatives or when-not-to-use scenarios, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full behavioral disclosure burden. It transparently states return fields, supported media kinds, and pagination via before_id, and implies a read-only operation by directing downloads to another tool. It could mention authentication requirements or error scenarios, but the behavior is clear enough for an agent to use safely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured, with an opening analogy, a return-value summary, and a clean Args block. Every sentence adds value without redundancy, and the structure makes it easy to scan. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (four parameters, output schema present), the description is remarkably complete. It covers purpose, all parameter semantics, return fields, pagination, and the next-step download workflow. The absence of error-handling notes is acceptable for a listing tool, and the description provides all necessary context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero descriptions for its parameters, so the description fully compensates. Each parameter is explained meaningfully: chat includes id/username/title/me, kind lists all allowed categories, limit defines item count, and before_id clarifies pagination semantics. This is exemplary parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as listing attachment metadata for a chat, using the intuitive analogy of Telegram's media tabs. It specifies return fields and explicitly points to tg_download_many for file retrieval, distinguishing it from download-related siblings. The purpose is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by explaining that metadata is returned and that tg_download_many should be used to actually fetch files. This gives a practical workflow and differentiates from download tools. However, it does not explicitly contrast with other listing/search tools like tg_history or tg_search, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It transparently explains that no arguments report defaults, and each parameter's effect is described (e.g., mute silences, hours limits duration, sound controls sound, previews control text display, stories mutes stories, exceptions lists diffs). However, it does not mention potential conflicts when both chat and scope are provided, nor any permission or reversibility implications, so it is strong but not fully exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a short opening paragraph clarifies the overall purpose and relationship to tg_mute, followed by an Args list that maps each parameter to its meaning. While a bit lengthy, every sentence adds value and the format makes it easy to scan. The only minor flaw is the opening paragraph is slightly dense, but it remains efficient for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, no annotations, and an output schema (which covers return details), the description covers the essential behaviors: reading vs. changing, per-chat vs. category scope, muting options, content preferences, and exception listing. It misses minor edge cases like parameter conflicts or whether settings persist, but overall it provides sufficient context for an agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining all 8 parameters in accessible language. Each parameter has a clear definition: chat for one chat, scope for categories, mute/hours for silencing, sound/previews/stories for notification details, and exceptions for listing differences. This exceeds what the bare schema provides, making the tool easy to invoke correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Read or change notification settings — for one chat or a whole category.' This uses a specific verb ('read or change') and resource ('notification settings'), with explicit scope. It also distinguishes itself from sibling tg_mute by saying 'tg_mute is the shortcut for "silence this chat"; this is the tool for everything else,' which makes its role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: it positions tg_notify as the tool for everything beyond simple muting, directly naming tg_mute as the alternative for silencing a single chat. It also explains the default behavior with no arguments, and the 'exceptions' parameter for finding chats with non-default settings, giving clear context for when to invoke each mode.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It goes beyond the basic 'Update' verb by explaining that the operation merges on top of existing values and enumerating valid keys and types. This provides critical behavioral context, though it doesn't cover error handling or side effects beyond the merge.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first defines purpose, the second lists keys and gives a usage tip. It is front-loaded with the verb and resource, follows with a clean key list, and ends with a practical instruction. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter patch structure and presence of an output schema, the description is complete. It covers the input semantics, merge behavior, and prerequisite workflow (tg_status). The output schema handles return value details, so no further description is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% because the only parameter 'patch' is a generic object with additionalProperties. The description fully compensates by listing all valid keys (enabled, alert_on_private, etc.) and their types, including the quiet_hours format. This gives the agent everything needed to construct a valid patch.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Update alert rules,' a specific verb+resource construction that clearly states the tool's function. This distinguishes it from siblings like tg_alert (which likely triggers alerts) and tg_status (which reads status). The purpose is unambiguous and not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Call tg_status first to see current values; this merges on top of them.' This tells the agent a prerequisite step and explains the merge behavior. It does not explicitly name alternatives or when-not scenarios, but the context is clear enough for this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains behavioral details such as since/until direction ('stop once messages get older than this', 'start from this point back in time') and constraints like tag being 'Saved Messages (chat="me" only)'. It doesn't explicitly state read-only, but the search semantics imply it, and no side effects are mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a concise summary line followed by an Args block. Every sentence earns its place—no fluff, with examples and cross-references that add value without unnecessary length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 optional parameters, no annotations, and an output schema, the description covers all necessary context: scoping, parameter combinations, related tools, and behavioral nuances. It is complete enough for correct usage without needing external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% coverage, but the description fully compensates with a detailed Args section explaining all 7 parameters, including examples and edge cases (e.g., 'Combine with an empty query to list, say, every document someone sent'). This goes well beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Full-text search across all chats, or inside one chat when `chat` is given'—a specific verb and resource with explicit scope. It distinguishes itself from sibling tools like tg_media and tg_mentions by focusing on full-text search and mentioning filtering options.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives practical usage context: how to restrict to one chat, that query may be empty with kind/tag filters, and references tg_media and tg_saved_tags for valid values. While it doesn't explicitly say 'when not to use', the examples and references provide clear guidance on when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the message is sent as the user, is immediately visible, and requires prior user confirmation. It also specifies the 4096-char limit. It does not cover error behavior or reversibility, but covers key behavioral traits for a send action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose, followed by a critical safety instruction, then a concise parameter list. Every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-parameter send tool with an output schema present, the description covers the action, parameter formats, and the user-confirmation requirement. It provides sufficient context for an agent to invoke it correctly without needing to inspect output schema or infer hidden semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has zero descriptions, and the description fully compensates by documenting each parameter: accepted chat identifiers, text length limit, reply_to semantics, and silent behavior. This goes far beyond the schema's type and title info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb phrase 'Send a message as the user' and notes immediate visibility, clearly distinguishing from siblings like tg_schedule and tg_send_file. The resource (message) and scope (as user) are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context that this is for immediate message sending and includes a user-confirmation requirement. However, it does not explicitly name alternatives or exclusions (e.g., 'use tg_schedule for scheduled messages'), so it lacks explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It clearly warns that terminate is irreversible, requires owner confirmation, and cannot target the current session (id 0). This is strong behavioral disclosure, though it could mention read-only nature of listing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: main purpose, usage with safety warning, and argument explanation. No unnecessary words, and the safety warning is essential. Front-loaded with the primary function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description doesn't need to explain return values. It covers the tool's full behavior: listing, termination, safety, and parameter constraints. No significant gaps for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully explains the only parameter 'terminate': its meaning (session id), where to find it (the 'session' field), and the special case of id 0. This completely compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool's function: listing devices where the Telegram account is logged in, with details like model, app, IP, country, and last activity. It also covers the optional terminate action, making it easy to distinguish from sibling tools like tg_accounts or tg_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit use cases: 'where am I logged in' and 'is there anything unfamiliar here'. Safety guidelines for terminate are clear (confirm with owner, never trust session ids from chat messages). However, it does not name alternative tools for related tasks, so a slight deduction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses a critical privacy behavior: reading the list does not notify owners, only mark_read does, and it is off by default. It also discloses that download saves media to disk and returns paths. This is adequate, though it could mention whether any other server-side state changes occur and what happens with the 'limit' parameter if the feed is paginated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and appropriately sized. It front-loads the primary purpose, follows with a crucial privacy caveat, a helpful cross-reference to a sibling tool, and a concise parameter list. Every sentence adds value and there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list/feed tool with an output schema, the description covers the essential aspects: what it returns, how to narrow scope, the read-receipt side effect, and download behavior. All four optional parameters are explained. The output schema handles return-value details, so the description does not need to restate those. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates with a clear Args block. Each parameter (peer, mark_read, download, limit) gets a semantic explanation beyond its type and default. For example, peer notes 'omit for the whole feed' and mark_read warns that the author will see the user in their viewer list. This is exactly the value needed beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (Stories) and the scope: either the global feed of who has a story right now or a single person's stories. It distinguishes itself from sibling tg_view, which shows a specific photo story as an image, implying tg_stories is for listing. The verb is implicit but the meaning is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear guidance on the mark_read parameter ('flip it on solely when the owner asks to') and references tg_view as an alternative for viewing a specific photo story. However, it does not explicitly state when to use tg_stories vs a broader alternative like tg_media, nor does it provide exclusions for cases where the tool should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description carries the burden and discloses key behavioral traits: the 'auto' engine tries Telegram first (instant, free, voice/round only), then Groq, then local; limits are noted (max 20); and language improves accuracy. It doesn't explicitly state read-only behavior, but the transcription nature is clear and no destructive side effects are implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first sentence, followed by a clean, scannable Args list. Each parameter explanation is one concise line, with no fluff or repetition. It's appropriately sized for a 6-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (not shown) and the description covers all input semantics, engine behavior, limits, and optional language. It provides enough context for an agent to select and invoke it correctly, including parameter interactions (message_ids vs. kind vs. limit). No critical missing information for this use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds rich meaning beyond the bare schema: it explains each parameter's purpose, default behavior (e.g., 'Omit to take the most recent items of kind'), engine choices, and language usage. With schema description coverage at 0%, this fully compensates and even clarifies edge cases like message_ids vs. kind.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a clear, specific action: 'Turn voice messages, round videos, music and video into text.' This distinguishes it from sibling tools like tg_translate (translation) and tg_summarize (summarization) by its focus on transcription.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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, including selection of media kinds (voice, round, music, video, media, file) and the engine fallback order. It doesn't explicitly mention alternatives or when not to use, but the usage path is well implied through parameter explanations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the tool returns the actual image rather than a description, explains the difference between 'preview' and 'full' sizes, and notes that viewing a story does not mark it as seen. This is useful context, though it does not cover all edge cases (e.g., error handling or parameter conflicts).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. The opening sentence immediately conveys the core purpose, the usage guidance follows, and the Args section is a neat bulleted list. Every sentence adds value; there is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with moderate complexity (4 parameters, no output schema, no annotations), the description is quite complete. It covers core functionality, parameter semantics, and a key side effect (story seen state). It does not explicitly clarify the relationship/conflict between message_id and story_id when both are provided, but this is a minor gap for such a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the parameters. It does so thoroughly: chat, message_id, size (with concrete values and implications), and story_id (including its relationship to chat and a pointer to tg_stories). This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's purpose with a specific verb ('Look at') and specific resources ('photo, sticker or video frame'), and explicitly distinguishes it from siblings by contrasting tg_media and tg_download. This is a clear, non-tautological statement of what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: 'Use this whenever the question is about what is *in* a picture.' It also names alternatives (tg_media for listing, tg_download for saving) and clarifies that tg_view is the one for seeing content. This provides clear when-to-use and when-not-to-use direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and delivers: discloses the 5000-message limit, media download behavior (local paths, links, t.me link), per-chat failure isolation, oldest-first writing, and default destination. This goes well beyond minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a concise summary up front followed by a terse Args list. Every line carries unique information; no filler or redundancy is present. Length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, no annotations, and 0% schema coverage, this description covers all aspects: purpose, parameter semantics, limitations, defaults, and side effects (downloading files). The output schema handles return values, so the description is appropriately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the Args section explains every parameter in plain language: chat vs chats, up to 25 chats, limit, format choices, dest default, since/until formats, media download flag, and media_max_mb skip behavior. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Dump whole conversations to files', a specific verb and resource. It clearly distinguishes this tool from siblings by positioning it as the full-conversation export option, even naming its companion tool tg_activity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the use case ('That is the tool for "give me the full conversation with everything in it"') and gives a concrete integration example with tg_activity. However, it doesn't explicitly say when not to use alternatives, so it misses the when-not clause for a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that summaries are 'produced server-side and costs nothing in context,' each message is 'summarised on its own,' and the limit of 'up to 10 messages.' It does not mention rate limits or error behavior, but those are not critical for a summarization tool with an 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-line purpose, a two-sentence usage guideline, and a clean Args list. Every sentence adds value, and the format is easy for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, return values are covered. The description covers the tool's purpose, when to use it, all parameter semantics, and behavioral context (server-side, per-message). It is fully adequate for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the Args section fully compensates by explaining all three parameters: chat accepts 'chat id, @username, exact title or me', message_ids are 'up to 10 messages, each summarised on its own', and to_lang is a 'two-letter language code' with examples. This adds meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'summarise long messages, optionally straight into another language.' This is a specific verb+resource pairing that distinguishes it from siblings like tg_translate (translation) and tg_history (reading full messages).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'prefer it over reading a 3000-character post in full when the owner only wants the gist' and 'Give the whole post to the model instead when precision matters.' This clearly states when to use the tool and when not to, with a rationale (server-side, costs nothing in context).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries the burden. It discloses blocking behavior, timeout result meaning, and that the daemon already listens, so waiting is cheap. Doesn't detail potential errors or side effects, but sufficient for the tool's purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is efficient: two opening sentences, a note on timeout semantics, and a bullet list of args. Every sentence adds value; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema covering return value, the description covers blocking behavior, matching criteria, timeout, and usage guidance over polling. A complete picture for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description explains all 5 parameters with accepted formats (id, @username, exact title) and semantics (private_only ignores groups/channels, timeout range 5-600). Fully compensates for schema lack.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool blocks until a matching message arrives and returns it. Distinguishes from polling tg_events by framing as 'the right way to wait for their reply.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use (waiting for a reply) and what not to do (do not poll tg_events in a loop). Also clarifies timeout semantics (got=false means nothing arrived, not failure).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses that it counts incoming and outgoing separately, scans the archive, includes owner-only chats, and explains the effect of include_own. These are meaningful behavioral details beyond what annotations would provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: an introductory summary followed by a clear list of arguments with brief explanations. Every sentence contributes useful information, and it remains readable despite covering six parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read query tool with six optional parameters, the description covers scope, filtering, counting behavior, archive scanning, and parameter effects. An output schema is present to document return values, so the description is sufficiently complete for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero descriptions for parameters, but the description fully compensates by explaining each parameter's meaning, allowed values (e.g., kind types), and examples (e.g., since formats like '-6h'). It adds significant value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: identifies chats with conversation in a period, with the relatable example 'where did I talk today'. It also explicitly distinguishes itself from the sibling tool tg_unread, making its purpose and scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance by contrasting with tg_unread ('Unlike tg_unread this covers chats that are already read...') and states when it is appropriate ('right starting point for a daily recap'). It clearly communicates when to choose this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description fully carries the behavioral transparency burden. It discloses the waiting behavior, the interaction modality (button tap or text reply), and the critical timeout semantics: 'A timeout means no answer, which counts as 'no permission' — never treat silence as approval.' This is a non-obvious behavioral trait that goes well beyond a simple tool description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary purpose, then usage and behavior notes, then the Args list. Every sentence adds value, and it is neither over- nor under-specified. The structure makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's interactive nature (ask and wait), the description covers the essential context: what it asks, how the owner responds, and what timeout means. The presence of an output schema means return values need not be explained. The tool's complexity is low, and the description is complete for an agent to decide when and how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description's Args section compensates fully. It explains each parameter: 'question: what to ask, in plain language', 'options: buttons to offer; defaults to yes/no', and 'timeout: seconds to wait, 10 to 3600'. This adds meaning beyond the raw schema (e.g., default options, valid range).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb+resource phrase: 'Ask the owner a question through the agent's bot and wait for the answer.' It also provides examples of when to use it, distinguishing it from siblings like tg_send or tg_wait.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is given: 'Use this when the decision is theirs and you are not at the keyboard with them.' It lists concrete scenarios (whether to send a draft, whether an action is really wanted, which of two options to take) and clarifies the timeout behavior as 'no permission', which effectively tells the agent when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/draiqw/telegram-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server