Claudegram

by sanjar-x

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.1.0
Disambiguation4/5
With 133 tools, some overlap exists between entity lookups (get_chat_info, resolve_username, get_input_peer) and message history variants (get_history, get_history_with_links), but most tools target distinct actions or resources. Descriptions are detailed enough to resolve ambiguity in most cases.
Naming Consistency5/5
All tools follow a consistent lowercase verb_noun snake_case pattern (e.g., get_history, send_message, create_channel). No mixed conventions or camelCase found.
Tool Count1/5
At 133 tools, the set is extremely large, far exceeding practical MCP server scope. While Telegram is a broad domain, this creates significant navigation and selection overhead, and most servers operate effectively with far fewer tools.
Completeness5/5
The tool surface covers nearly all Telegram features: auth, messaging, media, stickers, polls, stories, forums, admin, contacts, privacy, and more. The presence of invoke_raw ensures no capability gap, making the set highly complete for its domain.
Average 3.7/5 across 133 of 133 tools scored. Lowest: 2/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under MIT License.
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.json to 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?
Annotations declare readOnlyHint, idempotentHint, and destructiveHint false, which cover safety traits. However, the description adds no behavioral details such as pagination, response structure, or ordering, so it lacks sufficient transparency beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short but is an incomplete noun phrase rather than a proper sentence. While concise, it omits the verb and critical context, making it under-specified rather than efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and annotations, the description fails to clarify the tool's purpose or usage. For a four-parameter list operation, this is inadequate context for an AI 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.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention any of the four parameters (limit, compact, archived, is_pinned). The agent receives no semantic help beyond the parameter names and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'PM-боты в диалогах.' identifies the resource (PM bots in dialogs) but lacks an explicit verb like 'list' or 'fetch'. It does distinguish from sibling tools by scoping to private message bots, but the purpose is only clear when combined with the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 like list_pm_users or list_chats. The description gives no use cases, prerequisites, or contextual triggers.
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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds a small behavioral insight by clarifying that 'pinned' means 'saved in profile', which is helpful. However, it does not disclose pagination behavior, return format details, or any potential side effects beyond what annotations already convey. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase, which is not verbose, but it is under-specified rather than concise. It lacks a complete sentence, a verb, and any detail about what the tool does beyond the resource. The brevity does not serve a functional purpose here.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters and an output schema, the description is too minimal. It explains the core purpose but leaves out parameter usage, pagination, and relationship to sibling story tools. Although annotations and output schema cover safety and return structure, the description alone is insufficient for an agent to invoke the tool correctly with the right peer format or understand limit/offset semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 3 parameters (peer, limit, offset_id) with 0% description coverage, and the tool description provides no explanation of these parameters. The agent is left to infer from names alone. The description does not compensate for the lack of schema descriptions, so parameter semantics are inadequately conveyed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a noun phrase ('Pinned (saved in profile) stories of the user') rather than a clear verb+resource statement. It conveys what the tool returns but does not explicitly say 'get' or 'list', relying on the tool name. It does add context about 'saved in profile', which distinguishes pinned stories from other story types, but not strongly enough to differentiate among siblings like get_all_stories or get_stories_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not indicate when to prefer this tool over alternatives such as get_peer_stories or get_stories_archive, nor does it explain the meaning of filtering by peer or pagination parameters. There is no 'when to use' or 'when not to use' context.
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?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the destructive nature is known. However, the description adds no behavioral context beyond that—it doesn't mention permanence, irreversibility, ownership constraints, or that multiple stories are deleted at once. It simply restates the operation without supplementing the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very brief—a single phrase with no filler. It is concise in length but under-specifies the tool's behavior. While it earns points for not being verbose, it sacrifices necessary information, making it less effective than a slightly longer description that clarifies important aspects.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even though the tool is simple with one parameter, the description is incomplete. It doesn't explain the effect of the operation, whether deletion is permanent, or how the story_ids parameter works. The presence of an output schema and annotations does some work, but the description leaves the agent without critical operational context for a destructive action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description doesn't reference the story_ids parameter at all. The schema shows an array of integers, but the description doesn't explain what these IDs represent, whether multiple are accepted, or any format requirements. With such low coverage, the description fails to compensate, leaving the parameter semantics entirely to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Удалить свои истории' uses the specific verb 'удалить' (delete) and identifies the resource as one's own stories. This clearly distinguishes it from story-related siblings like send_story or get_stories_by_id, and the scope 'свои' (own) adds useful precision. However, it is minimal and doesn't mention batch deletion or other nuances, so it's clear but not fully detailed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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, no prerequisites, and no exclusions. Among many story-related siblings, there is no differentiation or context about when delete_stories is appropriate (e.g., when you need to remove your own stories by IDs). Usage is only implied by the name and surface description.
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?
Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds no extra behavioral context (e.g., irreversibility, permissions required, or effects on the chat). It merely repeats the action without enriching the agent's understanding beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise and free of filler. However, its brevity results in under-specification; it conveys only the basic purpose and lacks useful details, so it does not earn high marks for value per word.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a destructive operation with no output schema provided, the description should ideally disclose consequences, required permissions, or any restrictions. It provides none of this, leaving the tool contextually incomplete for a mutating action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema includes a required 'chat' parameter with no description, and schema_description_coverage is 0%. The tool description does not mention this parameter at all, leaving the agent entirely without guidance on what format or value to provide (e.g., ID, username, or peer).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('leave') and the resource type ('channel/supergroup'), which distinguishes it from sibling 'leave_chats' (plural). However, it does not explicitly clarify whether it applies to all chat types or only channels/supergroups, leaving slight ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 like 'delete_dialog' or 'leave_chats'. The description simply states the action without contextualizing it against other related tools.
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?
Annotations indicate a mutating, non-idempotent operation, and the description is consistent with that. However, it adds no extra behavioral context beyond the annotation flags—e.g., what happens to the sent card, whether permissions are needed, or side effects. The description is essentially a restatement of the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no fluff. It is appropriately short for the action, though it lacks useful structure or elaboration. It earns partial credit for brevity but not for content richness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters (3 required) and an output schema, the description is far from sufficient. It doesn't cover required fields, behavior, or return values. The tool is effectively under-documented for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no parameter details. It doesn't explain that 'chat' is the destination, 'phone' and 'first_name' form the card, or that 'silent' controls notification behavior. The description completely 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Отправить визитку контакта' translates to 'Send a contact card,' which clearly states a specific action (send) and resource (contact card). This differentiates it from sibling send_* tools like send_message or send_file, though it doesn't explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. It doesn't mention scenarios, prerequisites, or exclusions. The user must infer usage from the name alone.
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?
The description adds no behavioral context beyond what annotations already declare. Annotations indicate a write operation (readOnlyHint=false) and non-destructive, but the description does not explain effects, permissions, or error conditions. It does not contradict annotations, but it provides zero added transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase, which is under-specification rather than genuine conciseness. It lacks essential details and does not earn its place by adding value beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has two parameters and no parameter descriptions, yet the description provides no context about what the user should be, preconditions (e.g., user must be blocked), or the role of 'my_stories_from'. Despite having an output schema, the description is severely incomplete for an agent to use it reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does 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 parameters. The 'user' param could be an ID or username, and 'my_stories_from' is entirely cryptic. The description fails to compensate for the lack of parameter documentation, leaving the agent unable to correctly populate inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Unblock user' clearly states the action and target resource, and it is distinct from sibling tools like block_user by being the inverse operation. It is a specific verb+resource that leaves no ambiguity about the tool's core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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, such as when a user has been previously blocked or when to use unban_participant. It gives no context about prerequisites or exclusions, so the agent lacks usage direction beyond the name.
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?
The description adds no behavioral context beyond what annotations already provide. It doesn't mention that forwarding copies messages, preserves the source, or any permission/rate-limit considerations. With readOnlyHint=false and destructiveHint=false, the safety profile is known, but the description contributes nothing extra.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, extremely concise and front-loaded. It wastes no words, but it also omits substantive information. It earns high marks for brevity but loses a point for not using the space to add value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With five parameters, optional flags, and a mutation operation, the description is too sparse to be complete. It doesn't clarify the behavior of silent and drop_author, nor does it hint at response structure. The presence of an output schema reduces the need to document returns, but the overall contextual load is high and unmet.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description mentions none of the five parameters. The agent must rely solely on parameter names and types, which are somewhat self-explanatory but miss crucial details like accepted formats for chat identifiers or the effect of silent/drop_author flags.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: forwarding messages from one chat to another. It uses a specific verb and resource, which distinguishes it from siblings like send_message or edit_message. However, it doesn't explicitly contrast with similar tools, so it doesn't fully meet the highest bar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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, no prerequisites, and no exclusions. It only states what it does, leaving the agent to infer usage from the tool name and parameters.
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?
Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds no additional behavioral context such as reversibility, error behavior, or permission requirements. It merely restates the action without elaborating on consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is front-loaded and free of fluff, but it is under-specified for the tool's complexity. It leaves out usage and parameter details, so it is not appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk, destructive operation, the description is too minimal. It does not mention the batch nature beyond 'N', implications of archiving, or return behavior, despite having an output schema and a destructive hint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for 2 parameters. The description references 'N dialogs' but does not explicitly map this to the required chat_ids parameter, nor explain whether IDs can be integers or strings, or what the optional ctx parameter does.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Move N dialogs to archive', using a specific verb ('move') and resource ('dialogs'), with 'N' indicating a batch operation. This clearly distinguishes it from the singular sibling 'archive_dialog' and other dialog-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does 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 like 'archive_dialog', 'unarchive_dialog', or 'delete_dialogs'. The description lacks any context about use cases or exclusions.
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?
Annotations already signal destructiveness and non-read-only, but the description adds no additional context about side effects (e.g., whether the user is also removed from chats or if the contact entry is simply unlinked). It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, which is efficient. However, it is under-specified for a destructive tool, so the brevity comes at the cost of completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a single parameter and no textual clarification, the description is insufficient for an agent to correctly invoke the tool (e.g., what format to use for the user) or to understand prerequisites. Output schema exists but does not cover invocation context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does 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 'user' parameter. It fails to indicate whether an integer or string should be a Telegram user ID, username, phone number, etc., leaving the agent without necessary invocation details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and the resource (user from contacts). It distinguishes remove_contact from siblings like block_user and add_contact by specifically mentioning 'from contacts.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. It doesn't mention when to use delete_contact over block_user or unblock_user, nor any prerequisites 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?
Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the scope (supergroup/channel) but does not disclose behaviors like how pagination works, what 'search' searches, or whether specific admin roles are required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It is front-loaded but somewhat under-specified; however, conciseness is high.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters and an output schema, the description is too sparse. It fails to explain the nature of the admin log, the use of the search parameter, or any constraints. The agent would lack sufficient context to invoke it correctly without external hints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention or clarify any of the three parameters (chat, limit, search). The agent is left to infer parameter meanings solely from their names, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource as 'admin actions in supergroup/channel' and the tool name includes 'get', making the purpose reasonably clear. However, the description itself uses a noun phrase rather than an explicit verb, and it doesn't strongly differentiate from other log/history tools without the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives like get_history, get_chat_info, or search_messages. There is no mention of prerequisites, context, 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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the behavioral scope that only expired but not deleted stories are returned, which is useful context beyond the annotations. However, it does not mention pagination or ordering behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that is front-loaded and free of extraneous words. It earns its place by conveying the core purpose, though it is arguably too terse and could benefit from additional guidance without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists, alleviating the need to describe return values, the description lacks usage context, pagination semantics, and differentiation from sibling story tools. For a simple getter with two parameters, the description is minimally adequate but leaves notable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions for 'limit' and 'offset_id', and the tool description does not mention them at all. With 0% schema_description_coverage, the description carries the burden of explaining parameter semantics, but it fails to do so, leaving the agent to guess at cursor-based pagination.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as the archive of the user's own stories, adding the qualifier 'истёкшие, но не удалённые' (expired but not deleted). This distinguishes it from sibling story tools like get_all_stories or get_peer_stories. However, it lacks an explicit verb like 'retrieve' or 'list', though the tool name 'get_*' compensates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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, nor does it mention any exclusions or preconditions. It simply states what the archive contains, leaving the agent to infer usage from the name and context.
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?
The description adds no behavioral detail beyond what annotations already convey (readOnly=false, destructiveHint=false). It states the core action but does not disclose potential side effects, permission requirements, group type nuances, or limitations. 'Regular group' and 'specified participants' are essentially part of the core function rather than additional 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that gets straight to the point. It is concise and front-loaded, with no filler. However, it is so minimal that it lacks any structural breakdown or additional useful detail, though it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 parameters) and the presence of annotations and an output schema, the description is minimally viable but has clear gaps. It does not explain what 'regular group' means relative to Telegram group types, nor does it mention any edge cases or prerequisites. It is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description only vaguely references 'participants' which likely maps to the 'users' parameter, but it does not explain the 'title' parameter or clarify that users can be integers or strings. This 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool creates a regular group with specified participants, using a specific verb ('Создать') and resource ('обычную группу'). It distinguishes itself from the sibling 'create_channel' by specifying 'regular group' rather than a channel, though it does not explicitly compare with other group-like tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as 'create_channel' or 'join_chat'. The description mentions no context, prerequisites, or exclusions, leaving the agent to infer usage solely from the action name.
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?
Annotations indicate a non-read-only, non-idempotent, non-destructive mutation, but the description adds no behavioral context. It does not disclose that the avatar is replaced, whether admin permissions are required, or how the file is accessed (local path vs upload). This is a significant gap for a mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with zero filler. It states the core purpose directly, which is appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the operation is a mutation with no behavioral or usage context, the description is incomplete. It does not explain return values (though output schema exists, the description is still lacking prerequisites and edge cases) or usage scenarios. For a tool of this simplicity, more context is needed to avoid misuse.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 implicitly maps 'chat/channel' to the 'chat' parameter and 'file' to 'file_path', but does not clarify accepted formats (peer identifiers, path types) or any constraints. Minimal added value over the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Set the chat/channel avatar from a file.' It specifies the verb (set), the resource (avatar), and the target (chat/channel), distinguishing it from title/about edits and file sending. Slight lack of differentiation from sibling tools, but scope is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like send_file or edit_chat_title. The description does not mention prerequisites (e.g., admin rights) or exclusions, leaving the agent to infer usage.
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?
The description adds no behavioral context beyond the annotations. It does not mention potential side effects, permission requirements, or failure modes. Annotations already indicate it is a write operation, but the description contributes no extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded, with no unnecessary words. It is a single short phrase that immediately conveys the operation, though it may be too sparse for comprehensive understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given 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 parameter guidance, usage context, or behavioral notes. With only a bare action phrase, the agent has insufficient information to invoke the tool correctly with confidence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does 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 either parameter. The agent must infer that 'chat' refers to the target chat and 'title' to the new title, but no explicit semantic clarification is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Rename chat/channel' clearly states the operation and the target resource, distinguishing it from related tools like edit_chat_about and edit_chat_photo. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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, whether admin rights are needed, or how it differs from alternatives. The description simply states the action without any contextual usage instructions.
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?
The description adds no behavioral information beyond what the name and annotations already convey. Annotations already declare read-only, idempotent, and non-destructive behavior. The phrase 'common chats' is essentially a restatement of the tool name, providing no extra context about pagination, result format, or edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no wasted words, earning a high score for conciseness. However, it is so brief that it merely restates the tool name, missing opportunities to add valuable context; this slight redundancy prevents a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the output schema, and complete annotations, the description is minimally viable: it states the core purpose. However, it lacks usage guidelines and parameter semantics, and the presence of many sibling tools makes the lack of differentiation guidance a notable gap. It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero description coverage, and the description does not compensate. While 'user' is implicitly referenced as the specified user, the description does not clarify whether it accepts an ID or username (schema allows both) or explain the 'limit' parameter (default 50). The agent gets no additional meaning beyond the bare parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Общие чаты с указанным юзером' clearly identifies the resource (common chats) and the scope (with a specified user), distinguishing it from other chat-list tools like list_chats or get_dialogs_by_ids. The verb is implied by the tool name 'get', so the action is understandable, though not explicitly stated in the description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention scenarios, prerequisites (e.g., needing a user ID or username), or exclude other tools like search_global or list_chats. The description solely states the function without contextual usage advice.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read-only profile. The description adds a small behavioral detail about include_supergroups affecting the returned group types. It does not contradict annotations and provides no misleading information, but also does not disclose return format or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and the Args section is succinct. However, the opening phrase 'Groups and supergroups.' largely restates the tool name and adds little value. It is concise but under-specified, lacking important parameter details that could fit without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, no schema descriptions, and only a partial cross-reference, the description is inadequate for correct invocation without external knowledge. The presence of an output schema and read-only annotations mitigates some risk, but the parameter semantics gaps and absence of usage context make the tool incomplete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must clarify parameters. It explains include_supergroups and refers to list_channels for five other parameters, but leaves limit, archived, and only_unread completely unexplained. This partial coverage is insufficient for a tool with 8 parameters, leaving the agent to guess about important filtering options.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The resource is clearly identified as 'Groups and supergroups', distinguishing it from sibling tools like list_channels and list_pm_users. Although the description lacks an explicit verb, the function name 'list_groups' supplies the action, making the purpose understandable. The phrasing is terse but effective.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a distinction between basic groups and supergroups via include_supergroups=False, but does not explicitly state when to use this tool versus list_channels or other listing tools. The cross-reference to list_channels is indirect and does not clarify selection criteria. There is no explicit when-to-use 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the operation is known to be a non-read write action. However, the description adds no additional behavioral context, such as whether unbanning allows the user to rejoin, whether it fails if the user isn't banned, or any permission requirements. It offers nothing beyond the tautological 'unban'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded with the action and object. However, it is so short that it borders on under-specification, but for conciseness alone it earns a high score because there is no redundancy or irrelevant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool exists within a rich set of moderation sibling tools (ban_participant, kick_participant, restrict_participant), yet the description does not relate to them or explain the context of use. There is no mention of reversibility, effect on user access, or any edge cases. While the output schema exists, the description remains incomplete for an agent to understand the full behavioral scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention the parameters at all. It does not clarify that 'chat' and 'user' are identifiers (chat ID and user ID), nor does it explain how to represent them (integer vs string). With no compensation from the description, the agent has no semantic guidance for the two required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Снять бан с участника' clearly states the action (remove/unban) and the exact resource (a participant's ban). It unambiguously distinguishes this from sibling tools like ban_participant or kick_participant, and even from unblock_user, because it specifies 'бан' (ban) in a participant context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. It does not mention that this is the inverse of ban_participant, nor does it specify prerequisites like admin permissions or that the user must currently be banned. There is no explicit context or exclusion, leaving the agent to infer usage from the name.
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?
Annotations already indicate a non-read-only, non-idempotent write operation. The description adds no additional behavioral context such as required permissions, failure modes, side effects, or return behavior. It only states the basic action and optional icon parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a clear structure: a purpose sentence followed by an Args list. Every word earns its place, and there is no filler. The minimalism contributes to under-specification, but as a conciseness measure it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With four parameters, required chat/title, and a family of sibling forum-topic tools, the description is too sparse. It omits required parameter semantics, return value details, and error conditions, making it insufficient for confident invocation in many realistic scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 icon_color and icon_emoji_id but omits the required parameters chat and title, leaving ambiguity about accepted chat identifier formats and title constraints. This is a notable gap for the two most important parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Создать новую тему в forum-супергруппе' (Create a new topic in a forum supergroup), identifying the specific verb, resource, and context. It distinguishes this tool from siblings like edit_forum_topic and delete_forum_topic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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, no prerequisites, and no exclusions. It does not mention that the chat must be forum-enabled or that certain permissions are required, leaving the agent without decision criteria.
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?
Annotations already indicate this is a non-read-only, non-destructive, non-idempotent operation, so the description carries little extra behavioral burden. It adds the 'pin/unpin' dual action and 'in header' scope, but does not disclose side effects, defaults (e.g., pinned=true), or what happens if the topic is already pinned. This is minimal value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundancy, which is easy to parse. However, it is under-specified for a tool with three parameters, and the lack of detail slightly detracts from its effectiveness, though it remains appropriately front-loaded with the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters and is a write operation, the description is far too sparse. It fails to explain how to unpin (set pinned=false), the role of `chat`, or how this tool relates to siblings like `reorder_pinned_forum_topics`. An output schema exists but is not described, leaving the agent without sufficient context to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 explaining parameters. It only hints at 'тему' (topic) aligning with `topic_id` and the pin/unpin concept implying `pinned`, but completely omits `chat`. There is no explanation of what `chat` refers to (e.g., the forum) or how the parameters interact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: pin/unpin a forum topic in the header. It uses a specific verb ('pin/unpin') with a specific resource ('topic'), and the 'in header' qualifier distinguishes it from sibling tools like pin_message or pin_dialog. This makes the tool's intent unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. For instance, it doesn't mention that the `pinned` parameter controls whether to pin or unpin, nor does it contrast with `reorder_pinned_forum_topics`. There is no indication of prerequisites or context that would help an agent choose this tool.
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?
Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds no additional behavioral context. It does not disclose whether the scheduled messages are removed after sending, whether the operation can be partially applied, or if any special permissions are required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. It directly states the action and subject, achieving maximum conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two required parameters and an output schema, the description offers minimal context. It does not explain the effect on the scheduled messages (e.g., are they removed?), whether all messages in a chat are affected or only the specified message_ids, or any side effects. While the output schema is present, the description itself is incomplete for real-world use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of 'chat' or 'message_ids'. The parameter names are somewhat self-explanatory, but the description fails to clarify that message_ids refers to scheduled message identifiers, which is essential for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('send') and resource ('scheduled messages') with the adverb 'now' indicating immediate action. It clearly distinguishes this tool from siblings like delete_scheduled or get_scheduled_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/5
Does 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. It does not mention that this is for triggering already-scheduled messages rather than sending new unscheduled ones, nor does it reference any prerequisites or exclusions.
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?
The annotations already indicate this is a write operation (readOnlyHint=false) but not destructive. The description adds no additional behavioral context, such as whether votes can be changed, if the user must not have voted already, or any side effects. It is a bare operation description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, consisting of a one-sentence purpose and a single parameter specification. Every word is functional, but it lacks sections for the other parameters, making it too sparse to be highly effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three required parameters and no schema descriptions, the description should cover all of them and provide context. It covers only one parameter and gives no usage guidance or behavioral context. The presence of an output schema doesn't compensate for the missing parameter and usage information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions (0% coverage), so the description must compensate. It explains option_indices with 0-based indexing and the single/multiple distinction, but it does not explain chat or message_id, which are required and would help identify the poll message. This leaves ambiguity for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Проголосовать в poll' clearly states the operation: vote in a poll. It uses the specific verb 'vote' and resource 'poll', distinguishing it from sibling tools like send_poll (create) and get_poll_results (read).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No information is provided about when to use this tool or how it differs from alternatives. There is no mention of prerequisites such as having a poll message or constraints. The description gives no exclusions or alternatives.
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?
Annotations already declare readOnlyHint and non-destructive behavior, so the bar is lower. However, the description adds no behavioral context beyond the basic get operation—no mention of limits, not-found behavior, or ordering. It simply restates the purpose without disclosing additional 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no superfluous words. It is front-loaded with the action and resource, though it sacrifices necessary context for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While an output schema exists and annotations cover safety, the two required parameters are completely undocumented, and there's no guidance on usage limits or relationship to sibling tools. For a read-mostly tool, this level of description is insufficient given the 0% parameter coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does 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 what 'chat' represents (e.g., forum identifier) or how topic_ids should be structured. The mention of 'by their id' is too vague to compensate for the complete lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'get' with a clear resource 'forum topics by id', distinguishing it from sibling 'get_forum_topics' which likely retrieves all topics. The Russian text is unambiguous about targeting specific topics by their identifiers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when specific topic IDs are known, but it does not explicitly state when to prefer this over get_forum_topics or mention any exclusions. No alternative tools are referenced.
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?
Annotations already cover safety (read-only, open-world, idempotent, non-destructive). The description adds the scoping detail that bots are excluded, which is useful. However, it does not mention default behaviors, pagination, or how filters like archived/pinned apply. Given strong annotations, this is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short phrase with no wasted words. However, it is under-specified, omitting important details about filters and behavior. This is not true conciseness but rather brevity at the cost of clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 optional parameters and an output schema, the description is too sparse. It does not clarify what 'compact' does, how archived/is_pinned/only_unread filters work, or the significance of the default limit. The annotations and output schema fill some gaps, but the description should provide more orientation for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 five parameters. Parameter names like 'limit', 'compact', 'archived' are somewhat self-explanatory, but the description adds no meaning beyond the schema. It 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource: private chats with users (excluding bots). This distinguishes it from sibling tools like list_channels, list_groups, and list_bots. The verb is implied but made clear by the tool name 'list_pm_users'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit usage guidance is provided. The phrase 'without bots' hints at when to use this tool over list_bots or list_chats, but there are no instructions on when to prefer alternatives or any exclusions. The intended use is 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?
Annotations already indicate this is a mutating, non-idempotent, non-destructive operation. The description adds that rights are configurable ('с заданными правами'), but it doesn't disclose important behaviors like whether existing admin rights are overwritten or whether authorization is needed. This is acceptable given annotation coverage 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential action efficiently. It is appropriately concise with no filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of an 18-parameter mutation tool, the one-sentence description is inadequate. It lacks usage guidance, parameter semantics, and behavioral details beyond the annotations. The presence of an output schema mitigates the need to explain return values, but the overall context remains incomplete for an agent to confidently invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 18 parameters with 0% description coverage, yet the description only mentions 'specified rights' without explaining any parameter. It doesn't clarify required identifiers (chat, user), the meaning of the boolean permission flags, or the rank field. The schema titles provide some semantics, but the description fails to compensate for the complete lack of parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Назначить участника администратором с заданными правами' clearly states the action (appoint as administrator) and resource (participant). It is specific enough to convey the core purpose, though it doesn't explicitly contrast with the sibling tool demote_admin, making differentiation mostly implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 like demote_admin or restrict_participant. The usage is only implied by the tool's name and description, with no mention of prerequisites such as requiring existing admin rights or the effects of re-promoting an existing admin.
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?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds the useful detail that clearing a draft synchronizes across all devices, but it does not discuss irreversibility, permission requirements, or any other side effects beyond this sync note.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that states the action and a key side effect. It is front-loaded, direct, and free of unnecessary words, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While an output schema exists and annotations cover safety, the description fails to clarify the 'chat' parameter, which is essential for invocation. The overall context is minimal, leaving ambiguity about how to specify the chat target and what the underlying behavior fully entails.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'chat' has no description in the schema (0% coverage) and the description does not explain what format or value it expects. The anyOf integer/string type is ambiguous, and the agent receives no guidance on what constitutes a valid chat identifier.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Очистить' (clear) with the resource 'draft в чате' (draft in chat), unambiguously identifying the action. It distinguishes itself clearly from sibling tools like save_draft, get_drafts, and delete_message by focusing on drafts specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. It does not mention prerequisites, exclusions, or differentiate from similar tools like save_draft or get_drafts. The implied usage is clear but there is no explicit contextual advice.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. However, the description adds no behavioral context beyond the basic purpose, such as error handling for invalid IDs, rate limits, or the fact that multiple stories are fetched at once via the story_ids array. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler or redundancy. It is entirely front-loaded and earns each word. This is an appropriate size for a simple read operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although annotations and an output schema are provided, the description is insufficient for an agent to confidently select this tool among nine story-related siblings. It lacks usage guidelines and parameter clarity, which are critical given the presence of similar tools like get_all_stories and get_peer_stories. The tool's complexity is low, but the description fails to convey its unique applicability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only hints at 'by their id' which maps to story_ids, but does not explain the purpose of the 'peer' parameter. Since coverage is low, the description should compensate by explaining both parameters, but it only partially covers one, leaving the agent without sufficient semantic understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Получить конкретные истории по их id.' clearly identifies the tool's purpose as retrieving specific stories by their IDs, using a specific verb ('Получить') and resource ('истории'). This distinguishes it from sibling tools like get_all_stories, get_peer_stories, and get_pinned_stories, which have broader or 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 Guidelines2/5
Does 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. It does not mention scenarios where one would prefer get_peer_stories over this, nor does it give any exclusions or prerequisites. The only implied usage is from the tool name and schema, but no explicit context is provided.
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?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. However, the description adds no behavioral context beyond the bare purpose—nothing about irreversibility, partial failures, or what leaving actually entails. This provides no extra transparency beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It efficiently communicates the core action and is appropriately sized for the tool's apparent simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has four parameters, destructive behavior, and an output schema, the description is incomplete. It provides no information about how to specify chats, partial success behavior, or the impact of retry parameters. The description leaves too many operational questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only minimally implies `chat_ids` via 'N каналов'. It does not explain that identifiers can be integers or strings (e.g., usernames vs. numeric IDs), nor does it address `ctx`, `auto_floodwait_retry`, or `max_total_wait_seconds`. The description fails to compensate for the lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Выйти из N каналов/супергрупп одним вызовом' clearly states the tool's function: leaving multiple channels/supergroups in a single call. This explicitly distinguishes it from the sibling `leave_chat` by emphasizing batch operation, which is a specific verb+resource+scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies batch use through the plural 'chats' and 'одним вызовом' (in one call), but it does not explicitly state when to prefer this tool over the singular `leave_chat` or any alternatives. There is no clear when-to-use or when-not-to-use guidance, only an implicit context.
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 adds the behavioral detail that the dialog is pinned to the top of the list ('в шапке списка'), which is useful. However, it does not disclose potential side effects (e.g., max pins, overriding existing pins) or permission needs. Annotations already cover readOnly=false and destructive=false, but the description adds limited value beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is appropriately sized and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple purpose and an output schema exists, but the description is too minimal. It lacks parameter semantics and usage guidance, leaving the agent without enough information to reliably invoke the tool. The description covers only the basic action, ignoring important details like parameter meaning and expected behavior for different inputs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does 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 'chat' or 'pinned'. The description implies the action of pinning/unpinning but does not clarify what types of values 'chat' accepts (integer or string) or how 'pinned' controls the action. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: to pin/unpin a dialog at the top of the list. The verbs 'pin/unpin' are specific and the resource 'dialog' is identified, distinguishing it from sibling tools like pin_message or pin_forum_topic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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, nor does it mention any prerequisites or conditions (e.g., permission requirements). It simply states the action without context.
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?
Annotations already indicate a write operation (readOnlyHint=false) and non-destructive behavior. The description adds no further behavioral traits such as permission requirements, side effects, or scope of change, leaving the tool's behavior minimally disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence that is front-loaded and contains no wasted words. It is appropriately concise for a simple setter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimally viable given the presence of annotations and an output schema, but it lacks context about when to use the tool, required permissions, or limitations relative to sibling tools. More contextual detail would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate for parameter meaning. It clarifies that 'about' refers to the chat's about/bio, but it leaves 'chat' ambiguous—likely an identifier, but no format or acquisition method is provided. This is insufficient for full parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Set chat description (about/bio)' clearly states the action (set) and the target resource (chat description), distinguishing it from sibling tools like edit_chat_title and edit_chat_photo.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 such as edit_chat_title, update_profile, or other chat-editing tools. It also omits prerequisites like required permissions or applicable chat types.
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?
Annotations already declare a non-read-only, non-destructive, non-idempotent operation. The description adds the folder=1 detail but does not explain the effect on dialog visibility, recoverability, or any side effects. It does not contradict annotations, but adds only marginal 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no redundant wording. The action is front-loaded and the folder detail is compactly included. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the presence of an output schema and annotations, the description is too sparse. It fails to explain the 'chat' parameter, prerequisites, or what happens after archiving. For an AI agent to invoke it correctly, additional external knowledge about the parameter and expected behavior is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The required 'chat' parameter is documented only in the schema as integer or string, with no description. The tool description does not explain how 'chat' identifies the dialog or what formats are accepted. With 0% schema description coverage, this is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Переместить' (move) and resource 'диалог' (dialog), clearly indicating the action of archiving. The folder=1 detail further specifies the target archive. It distinguishes from siblings like 'unarchive_dialog' by the opposite 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/5
Does 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 the plural 'archive_dialogs' or the reverse 'unarchive_dialog'. The description offers no context about single vs. batch operations or exclusions, leaving the agent to infer usage from the name alone.
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?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds specific metadata fields returned but does not disclose behavior for messages without media or error conditions, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the core purpose. It has no waste but could be slightly more structured to include usage or parameter hints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with an output schema and annotations, the description covers the basic purpose. However, it misses usage context and edge-case behavior, making it minimally sufficient but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 'chat' or 'message_id' parameters. The agent must rely on parameter names alone, which may be ambiguous for the 'chat' format (integer vs string).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves media metadata (type, size, mime, dimensions, duration) from a message. This is specific and distinguishes it from sibling tools like download_media or send_file, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives, nor any prerequisites such as the message containing media. It only states what it does, leaving the agent to infer usage from the name.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds minimal behavioral content (only that it includes 'features, prices') but does not disclose details like return format, localization, or any side effects. Since annotations carry most of the transparency burden, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely compact—a single short phrase with no filler words. It is front-loaded and every word adds value (promo material, features, prices). Conciseness is exemplary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, read-only tool with rich annotations and an output schema, the description, while minimal, covers the basic semantics (what the promo material contains). It could be improved by adding a verb and clarifying the return behavior, but given the low complexity, the current level is nearly adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so there are no parameter semantics to explain. The description does not need to elaborate on parameters, and the baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a noun phrase ('Промо-материал Telegram Premium (фичи, цены)') that names the resource and its content (features, prices) but lacks a verb specifying the action. The tool name 'get_premium_promo' implies retrieval, but the description itself is vague and does not explicitly state that it returns the promo material.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. There is no mention of context, prerequisites, or exclusions. The description only gives a static phrase with no actionable direction.
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 annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds context about the Telegram catalog and the exclude_featured parameter, but does not disclose pagination, result limits, or other behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct, with a one-line purpose followed by an Args list. Every sentence earns its place, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations and an output schema present, the tool is largely covered. However, the required query parameter is not documented, and there is no usage context. This leaves gaps for a simple search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description documents only exclude_featured ('exclude featured sets from the output'), providing meaning beyond the schema's type and default. The required query parameter is not explicitly described, though its meaning is implied by 'search by name'. With schema description coverage at 0%, the description only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'search sticker sets by name' (Поиск стикерсетов по имени), clearly identifying the action and resource. It is specific enough to distinguish from related tools like get_sticker_set, though it does not explicitly mention alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 such as get_sticker_set or search_global. The description gives no context about recommended usage, prerequisites, 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?
Annotations already indicate a write operation (readOnlyHint=false). The description adds the meaningful detail that setting live_period (60-86400) sends a live location. However, it does not disclose other behavioral aspects such as whether silent affects delivery or whether the chat must be a group or private conversation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the purpose. The Args section is minimal and directly useful, and every sentence earns its place without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (3 required) and an output schema, the description is too sparse. It omits essential context about required parameters, the meaning of silent, and how to specify the chat target. The live_period detail is helpful, but overall the description does not provide sufficient guidance 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description only explains live_period. It does not clarify the format or meaning of chat, latitude, longitude, or silent. While latitude and longitude are self-explanatory, the chat field's anyOf type and silent's effect are left undocumented, making parameter understanding incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Отправить геолокацию' clearly states the action (send) and the resource (geolocation), which is specific and distinguishes it from sibling send tools like send_message or send_contact. 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 Guidelines2/5
Does 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 such as send_message or send_contact. The only usage hint is the live_period parameter behavior, but there is no mention of prerequisites, chat requirements, or scenarios where this tool is 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?
Annotations already indicate a write operation (readOnlyHint=false), so the description doesn't need to state that. It adds a useful constraint (user must exist) and a privacy-related behavioral note about add_phone_privacy_exception. However, it does not disclose side effects, reversibility, or auth requirements beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and uses a clear bullet-list format for parameters. It is front-loaded with the main action, but the omission of required parameters is a structural flaw that costs it a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters, 2 of which are required, and the description misses the required first_name. It also lacks context about return values, error conditions, or behavior when adding an already-existing contact. The description is inadequate for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the meaning of user, phone, and add_phone_privacy_exception, but it completely omits first_name and last_name, even though first_name is required by the schema. With schema description coverage at 0%, this is a critical gap that leaves the agent unable to correctly fill required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action with a specific verb ('Добавить' = Add) and resource ('пользователя в контакты' = user to contacts). It distinguishes from sibling tools like delete_contact, import_contacts, and block_user by specifying the singular, direct action of adding a single contact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying the prerequisite that the user must already exist ('существующего юзера'), but it does not explicitly state when to use this tool versus alternatives like import_contacts or send_contact. No exclusions or alternative recommendations are 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?
The description adds behavioral context beyond the annotations by explaining that broadcast channels allow only admins to write and that megagroup=True creates a supergroup. However, it fails to disclose the behavior when both flags are set or when neither is set, and it does not mention potential side effects or permissions needed. The annotations provide the safety profile, but the description leaves edge cases 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and covers the key flag distinctions in a compact format. The Args block is structured, but the language could be more formal and the layout slightly clearer. Overall, it earns its place without excessive verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and the existence of an output schema, the description is minimally sufficient. It explains the two core flags but lacks guidance on parameter defaults, mutual exclusivity, and the practical difference from create_group. The description does not fully equip an agent to handle conflicting flag values or understand the exact behavior of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description is responsible for explaining parameters. It does explain broadcast and megagroup semantics well, but it does not elaborate on the 'title' or 'about' parameters, even though these are part of the schema. The description partially compensates but leaves two parameters undocumented in prose, relying on the schema titles alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a channel or supergroup, with specific references to the broadcast and megagroup flags. However, it does not differentiate itself from the sibling tool create_group, leaving some ambiguity about when to use this tool versus that one for basic group creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by explaining that broadcast=True creates a broadcast channel and megagroup=True creates a supergroup, giving context for the two primary modes. However, it does not explicitly state when to use this tool over create_group or other alternatives, nor does it mention any exclusions 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?
The annotations already indicate destructiveHint=true, so the agent knows this is a destructive operation. The description adds no extra behavioral context beyond the literal meaning of 'delete'—it does not mention irreversibility, the effect on chats within the folder, or any prerequisites. Thus, no additional value over annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly conveys the tool's core purpose. No filler, front-loaded and unambiguous.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given 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, annotations provide safety), so the minimal description is adequate. However, it leaves gaps such as the need to obtain filter_id from a list operation and the fact that only the folder is deleted, not its contents. It is minimally viable but lacks richer context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter, filter_id, with no description (0% coverage). The description does not explain what filter_id refers to or how to obtain it. The parameter name is self-explanatory given the tool name, but the description adds no semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Удалить кастомную папку диалогов' clearly states the action (delete) and the resource (custom dialog folder). It distinguishes itself from sibling tools like get_dialog_filters and create_dialog_filter by specifying the delete operation on a filter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied: if you need to remove a custom folder, this is the tool. However, it does not explicitly mention alternatives or exclusions (e.g., use delete_dialog for individual chats), nor does it advise obtaining filter_id from get_dialog_filters first.
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?
Annotations already declare the operation as read-only, idempotent, and non-destructive, covering the safety profile. The description adds meaning to 'top' and enumerates categories but does not disclose how the top is computed, whether results are sorted, or how the limit parameter affects behavior. This is acceptable 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, with a clear purpose statement followed by parameter documentation. It avoids unnecessary fluff. However, the omission of the 'limit' parameter documentation is a minor structural gap, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with an output schema, the description covers the core concept and category options but fails to document the limit parameter. Since the schema itself lacks property descriptions, the tool description is the primary source for parameter meaning, and its incompleteness leaves a gap. Overall, adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 documents the 'category' parameter with an explicit list of allowed values, which adds meaning beyond the schema. However, the 'limit' parameter is completely unmentioned in the description, leaving its semantics unclear. With one of two parameters covered, partial compensation is achieved.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'Топ часто-используемых контактов' (top frequently used contacts) in a specified category. The category list further specifies the resource scope, distinguishing it from sibling tools like get_contacts or list_chats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. It does not mention specific use cases, exclusions, or prerequisites. The category enumeration provides context but does not explain when get_top_peers should be preferred over other contact or chat listing 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?
Annotations already indicate non-read-only, non-destructive, and open-world behavior. The description adds one behavioral detail for the 'archived' parameter (adds to archived, not shown actively) but does not disclose other potential side effects, permission requirements, or what happens if the sticker set already exists. This provides some value beyond annotations but remains limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise line stating the purpose, followed by a brief parameter explanation. Every word earns its place, with no redundancy or filler, making it highly efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple two-parameter tool and the presence of an output schema, the description covers the core purpose and explains the non-obvious parameter. It doesn't mention prerequisites like authentication or the need to specify a sticker set's short name, but these are minor gaps for a straightforward install action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 meaning. It explains the 'archived' boolean well ('True — add to archived'), but the required 'short_name' parameter is not described at all, leaving its role ambiguous beyond the schema's title 'Short Name'. This partial compensation yields a moderate score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Install sticker set to account', identifying the verb, resource, and target. It distinguishes from siblings like uninstall_sticker_set and search_sticker_sets, though it doesn't elaborate on what 'install' entails beyond the archived parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 (e.g., get_installed_stickers, uninstall_sticker_set). It only states the basic action, leaving the agent to infer usage context without explicit exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, but the description adds no extra behavioral context such as idempotency, side effects, or permission requirements. The 'up to id' scope merely restates the max_story_id parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the core action. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and has an output schema, so return details are not needed. However, with no parameter explanations and no usage guidance, the description only covers the basic purpose. It is adequate but incomplete for guiding effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description only clarifies max_story_id ('up to the specified id') while leaving peer entirely unexplained. It does not adequately compensate for the missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('mark stories read') and the resource ('stories'), with a precise scope ('up to the specified id'). This differentiates it from sibling tools like mark_read (which likely targets dialogs) and story-specific read/delete tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when marking stories as read up to a certain ID, but it does not explicitly mention when to use this tool versus alternatives like mark_read or get_stories_by_id. No exclusions or alternative recommendations are provided.
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?
The description does not disclose behavioral traits beyond the action implied by the name. It adds a detail about access_hash sourcing, but annotations already convey mutating status (readOnlyHint=false). No rate limits, auth requirements, return behavior, or side effects are mentioned. There is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a heading and a clear args list. Every piece of information is useful and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with six parameters and zero schema descriptions, the description covers only three parameters and skips the essential chat destination as well as optional silent/reply_to. The returned output is not discussed (though output schema exists). The description is insufficient for correct invocation without additional inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains document_id as the sticker document identifier, access_hash as the set's access hash, and sticker_set_short_name as the source set's short name, adding meaning. However, it omits chat, silent, and reply_to parameters, and with 0% schema coverage, those remain unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Отправить стикер по document_id' (Send sticker by document_id), clearly specifying the action, resource, and method. This distinguishes it from sibling tools like send_file and send_media.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'получи через get_sticker_set' (get via get_sticker_set) identifies the source for the required identifier, providing a prerequisite. However, it gives no guidance on when to prefer this over alternatives, nor any exclusions or alternative scenarios.
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 adds a small behavioral context beyond the annotations by explaining that unmuting returns the chat to default settings. The annotations already indicate readOnlyHint=false and idempotentHint=false, so the description need not restate those. However, it does not disclose any side effects or clarify whether unmuting a non-muted chat is an error, leaving some transparency 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise phrase that is front-loaded with the key action ('Снять mute'). Every word earns its place, and there is no unnecessary filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and an output schema, the description covers purpose adequately but misses param semantics and usage guidance. The presence of an output schema reduces the need to explain return values, and the tool's low complexity means the description is minimally viable but still has clear gaps in guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, and the description provides no information about the 'chat' parameter. Since the description carries the full burden in this case, it fails to explain that 'chat' likely refers to a chat identifier or how it should be specified (integer or string). The description does not 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Снять mute' (remove mute) and the resource 'с чата' (from chat), making the tool's purpose unambiguous. It distinguishes itself from the sibling mute_dialog by being the direct inverse, and the parenthetical 'вернуть дефолтные настройки' adds clarity that it restores default settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its usage (when a chat is muted), but it does not explicitly state when to use this tool versus alternatives. It fails to mention that it is the counterpart to mute_dialog, though the sibling list makes that inferable. There are no exclusions or explicit when-not-to-use conditions.
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?
The description adds important behavioral context beyond annotations: it explains the dual behavior (leave vs delete) and the revoke parameter's effect, noting that deleting for the other side only works in PMs. This enhances the destructiveHint annotation, which already signals mutability. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with one sentence stating the core purpose and a short args block explaining revoke. Every word earns its place, and the structure is front-loaded with the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a destructive tool with annotations and an output schema, but it lacks clarity on how to choose this tool against similar siblings (leave_chat, delete_dialogs). It also doesn't mention potential side effects, reversibility, or whether the chat parameter accepts IDs or usernames, though the schema partially covers the latter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides meaningful semantics for the revoke parameter ('True — удалить переписку и у собеседника (только PM)' i.e., delete correspondence for the other side, only in PMs). However, the required chat parameter is not explained at all beyond the schema's generic 'Chat' title, leaving a gap for the required argument with 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Покинуть чат/канал или удалить личный диалог' (leave chat/channel or delete personal dialog). It names specific actions and resources, distinguishing between two modes. However, it doesn't explicitly differentiate from sibling tools like leave_chat, so it lacks sibling-based differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives such as leave_chat, delete_dialogs, or archive_dialog. The overlap between 'leave chat/channel' and the sibling leave_chat tool creates ambiguity, and no exclusions or preferred-use cases are mentioned.
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?
Annotations already indicate this is a non-read-only, non-destructive operation with external effects. The description adds the 'own message' constraint, which is behavioral. However, it does not disclose other behaviors like edit limitations, formatting handling, or potential errors. Given the annotations, this is acceptable but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence in Russian, front-loaded with the core action. Every word is meaningful, and it avoids redundancy. It is exactly as short as it can be without losing the essential purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, 3 required, an enum, and a boolean, the one-sentence description is insufficient. It does not explain what the parameters affect, advanced constraints, or expected outcomes. The output schema exists but is not visible, so the description alone leaves too many gaps for the agent to make educated guesses.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no parameter semantics. The agent must rely on parameter names and the parse_mode enum for meaning. The description does not compensate for the missing schema descriptions, leaving parameters like chat, message_id, and link_preview partially underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Отредактировать своё сообщение' uses a specific action verb (edit) and a clear resource (own message), making it obvious what the tool does. The word 'своё' (own) adds a crucial constraint, distinguishing it from sibling tools like send_message and delete_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used to edit a message the user sent, but it provides no explicit when-to-use vs alternatives, prerequisites, or exclusions beyond the 'own message' qualifier. It gives enough context for basic use but lacks guidance on choosing between this and send_message or delete_message.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the limit range (1-100) and explaining pagination via offset_id/offset_topic, but does not disclose other behaviors like result ordering or default values, which is acceptable given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with purpose, followed by a clear arg list. It avoids unnecessary words, though the argument explanations are terse and could benefit from a bit more detail without compromising conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with an output schema, the description covers the main filtering and pagination options but omits the required 'chat' parameter description and any note about output structure (though output schema exists). This leaves the tool somewhat incomplete for a new agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 limit, search, offset_id, and offset_topic with meaningful details (range, filter, pagination). However, the required 'chat' parameter is completely undocumented in both schema and description, leaving a critical gap for this tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List of topics in forum-supergroup', using a specific verb+resource construction. It distinguishes itself from sibling tools like get_forum_topics_by_id (single topic) and create_forum_topic (creation) by indicating the list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing topics in a forum supergroup, but does not explicitly state when to use it over alternatives or provide exclusions. The context is clear enough from the resource type, but there is no direct comparison to sibling tools or guidance on scenarios.
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?
The description adds the admin constraint, which is not already present in the annotations. Since annotations already declare read-only, idempotent, and non-destructive behavior, this additional context is useful. It doesn't contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose and the admin constraint. Every word contributes value, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and annotations covering safety, the description provides the essential purpose. However, it lacks parameter semantics and sibling differentiation, leaving notable gaps for a simple tool that could have been fully specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 doesn't explain the `chat` parameter's format (e.g., username vs. numeric ID), though the name and context imply it's the channel/supergroup identifier. This is minimal guidance at best.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves statistics for a channel or supergroup, using a specific verb and resource. It narrows the scope but doesn't explicitly distinguish from sibling tools like `dialog_stats`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the admin requirement, providing a clear context for when this tool should be used. However, it doesn't offer guidance on choosing between this and similar stats-related tools, nor does it state any 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?
Annotations already indicate destructive behavior, but the description adds meaningful context by stating that the topic is deleted 'together with all messages,' which is an important consequence not evident from the tool name alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the key action and outcome. Every word is essential, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core destructive behavior, and annotations handle safety, while the output schema presumably covers return values. However, it lacks usage guidelines and parameter clarification, making it only minimally 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.
Parameters2/5
Does 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 'chat' or 'topic_id.' While the parameter names are self-explanatory to some degree, the description fails to clarify what chat refers to (e.g., forum chat) or how to obtain topic_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'delete' and identifies the resource 'forum topic' plus clarifies the scope ('with all messages'), which distinguishes it from sibling tools like edit_forum_topic or pin_forum_topic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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, prerequisites, or exclusions. The description simply states what the tool does without any contextual usage instructions.
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?
The description adds the specific behavioral detail that all admin flags are set to False, which goes beyond the annotations' destructiveHint. It clarifies exactly what gets modified, though it doesn't mention permissions or 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is appropriately sized for a simple tool, conveying the core action and mechanism efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the primary action adequately, and the output schema documents return values. However, it misses usage guidelines and parameter format details, leaving some ambiguity for a two-parameter tool. The annotations fill in the destructive nature, but the overall context is still minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the parameters 'chat' and 'user' at all. Schema coverage is 0%, and while the parameter names are self-explanatory, the anyOf integer/string types are ambiguous (e.g., ID vs username), which the description fails to clarify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Снять права админа' (remove admin rights) and adds the specific mechanism 'all flags to False'. This distinguishes it from siblings like promote_admin and other moderation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 such as ban_participant or restrict_participant. It only states the action without any usage context 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 annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds the scope of 'any entity' but does not add further behavioral context such as authentication requirements or rate limits. Since the annotations cover the safety profile, a middle score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short, front-loaded sentence that communicates the core purpose without redundancy. Every word is purposeful, and it is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter, no nested objects, and an output schema present), the description is mostly sufficient. It states the main function and entity scope, while the output schema handles return value details. Missing usage guidance slightly reduces completeness, hence a 4.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides a single 'chat' parameter of anyOf integer/string, and the description adds that it works for any user/chat/channel/bot, clarifying semantic scope. However, it does not explain acceptable formats (e.g., username vs. ID), so the description only partially 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool provides detailed information about any entity (user/chat/channel/bot). It uses a specific verb ('get') and resource ('entity info'), which makes the purpose understandable. However, it does not explicitly differentiate from sibling tools like get_full_user, so it stops short of a 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when you need entity details, but it provides no explicit when-to-use guidance or alternatives. There is no mention of situations where other tools (e.g., get_full_user) would be more appropriate, leaving the agent to infer usage.
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?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, establishing a safe, non-mutating operation. The description adds no extra behavioral details beyond the basic purpose—such as ordering, inclusion of blocked contacts, or pagination—so it contributes no new transparency beyond structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, brief sentence with no filler words. It is front-loaded with the core meaning and perfectly sized for a zero-parameter tool, earning every word it uses.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero parameters, output schema present), the one-line description is nearly complete. It could mention whether the list is sorted or includes all contact types, but the availability of an output schema and no parameters makes this adequate. A 4 reflects that it's sufficient but could offer marginal extra context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the absence of parameter details in the description is appropriate. The schema is fully covered (100% coverage) since there are no properties, and the baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as listing all contacts of the account, using the noun 'список' (list). It is easily distinguishable from sibling tools like add_contact, delete_contact, and import_contacts, and there is no ambiguity about the resource (contacts) and the operation (listing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 such as search_global or get_dialogs, and no exclusion criteria are mentioned. It simply states what it does, leaving usage context entirely implicit.
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?
The description adds no behavioral detail beyond what annotations already provide (readOnlyHint, idempotentHint, destructiveHint). It does not disclose whether all custom folders are returned, any pagination, or other runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the tool's purpose with no unnecessary filler. It is appropriately sized for a simple getter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, the presence of an output schema, and comprehensive annotations, the description provides sufficient context. It might benefit from a brief note about interactions with create/delete dialog filter tools, but this is not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema coverage is trivially 100%. The description need not add parameter details, and the baseline for 0-param tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: listing custom dialog folders (Telegram UI Folders). It is specific enough to distinguish it from sibling tools like create_dialog_filter and delete_dialog_filter, which handle folder creation and deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. It does not mention related operations such as creating or deleting filters, nor any when-not-to-use instructions. The intended usage is only implied by the tool's name.
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?
Annotations already mark this as read-only, idempotent, and non-destructive. The description adds behavioral context beyond that by explaining the output structure (compact text blocks + ResourceLink) and the lazy-loading pattern with the telegram://msg/{chat_id}/{message_id} resource.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: 'Гибрид: компактные text-блоки + ResourceLink на каждое сообщение' immediately conveys the core idea. The follow-up sentence adds practical client behavior without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's relative simplicity, the presence of an output schema, and rich annotations, the description is mostly complete. It explains the key output format and the resource-loading mechanism, though it could add a brief note on parameter meaning.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain the 'chat' or 'limit' parameters. It mentions chat_id in the resource link but doesn't clarify whether 'chat' accepts an ID, username, etc., or how 'limit' affects results. The parameter names are somewhat self-explanatory, but the low coverage is not compensated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly indicates a hybrid message history output: compact text blocks plus a ResourceLink per message so the client can load the full message. It distinguishes itself from sibling get_history by emphasizing the resource-link mechanism, though it doesn't use an explicit imperative verb like 'retrieves'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a use case: get a cheap, compact list of messages and lazy-load full messages via telegram:// resource links. However, it does not explicitly state when to use this over get_history or other alternatives, nor does it mention any 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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds the 'active' scope and peer targeting, but does not disclose pagination, ordering, or any permission nuances; annotations carry much of the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise Russian sentence that directly states the action and target. It is front-loaded and contains no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read-only story retrieval with strong annotations and an output schema, so the description doesn't need to explain return values. It covers the essential scope and target, though it could be slightly richer in relating to sibling story tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'peer' has no schema description (0% coverage) and is only typed as integer|string. The description adds that the target is a user/channel, which gives some semantic context, but it doesn't explain accepted formats such as username, phone, or channel ID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it retrieves active stories for a specific user/channel, which is a clear verb+resource combination. It distinguishes from broader story tools by specifying 'specific' and 'active', though it does not explicitly mention sibling tool 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'specific user/channel' implies this is the tool to use for per-peer active stories, but there is no explicit guidance on when to prefer it over get_stories_by_id, get_all_stories, or get_pinned_stories. No exclusions or when-not-to-use context 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?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds that it returns a list of results, which is useful context. However, it does not disclose potential side effects, rate limits, or the temporary nature of inline query results, leaving some ambiguity given the non-read-only 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the primary action ('make an inline query'), and contains no unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple and has an output schema, so return values are partly covered. However, the description omits parameter details and usage guidance, leaving limit and offset unexplained. It is minimally viable but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It clarifies 'bot' and 'query' through the '@bot query' example, but 'limit' and 'offset' are not explained, leaving them undocumented in both schema and description. Only partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs an inline query to a bot, analogous to typing '@bot query' in any chat, and returns the results. This is a specific verb+resource action that distinguishes it from siblings like click_inline_button or send_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear context (inline query in any chat) but does not explicitly say when to use this tool over alternatives, nor provides prerequisites or exclusions. The usage is implied by the action itself but not directly guided.
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?
Annotations already declare this is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds context about the notify behavior (sends notifications) and pm_oneside (PM-only self-pin), but does not disclose other behavioral traits such as whether an existing pin is replaced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two clear sentences. The main action is front-loaded, followed by parameter explanations. Every sentence carries useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple pin operation with an output schema present, the description adequately covers the core action and the non-default parameter behaviors. However, it lacks details on defaults (though schema provides them), edge cases, and the meaning of chat/message_id, making it only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 notify and pm_oneside, but omits the required parameters chat and message_id. Chat has an ambiguous type (anyOf integer/string) and message_id lacks any format context, leaving essential params poorly specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Закрепить' (pin) and resource 'сообщение в чате' (message in chat), clearly indicating the action and its target. This distinguishes it from the sibling tool unpin_message without needing explicit contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied: pinning is a well-known chat operation. However, there is no explicit guidance on when to use this tool versus alternatives like unpin_message, and no mention of exclusions or prerequisites.
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?
Annotations already declare this as a write operation (readOnlyHint=false) and non-destructive. The description adds the list of allowed values for the value parameter, which is useful, but it doesn't disclose any side effects, permission requirements, or behavior on invalid inputs. It is consistent with annotations, so no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct, with a one-line purpose followed by an args list. It avoids redundant language, though the Args block is a bit terse and could be better integrated with the schema. Still, every sentence earns its place and the front-loading is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter with an output schema, the description is nearly sufficient. The main gap is the meaning of 'key', which is mitigated by referencing get_privacy. The value options are fully enumerated, and the output schema covers return values, so overall completeness is adequate but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the full burden. It enumerates valid values for 'value' and directs users to get_privacy for 'key', which adds meaning beyond the schema. However, it doesn't explain the semantics of the keys themselves, only pointing to another tool, leaving partial ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action: 'Set privacy for the specified key' (Установить privacy для указанного ключа). This is a specific verb+resource pairing that clearly distinguishes it from the sibling get_privacy (the getter). The purpose is immediately comprehensible.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description hints at usage by referencing get_privacy for key definitions, implying users should consult the getter first. However, it doesn't explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites beyond that pointer.
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 adds behavioral context beyond annotations by stating that after enabling, the supergroup becomes a 'forum.' It also notes the member requirement. However, it does not disclose side effects of disabling, reversibility, or the effect of the `tabs` parameter. Annotations already indicate mutation (readOnlyHint=false), so the description adds some but not rich behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core action, and contains no filler. Every sentence provides relevant information: what the tool does and a key prerequisite.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the primary action and the main constraint (≥200 members), and an output schema exists so return values need no explanation. However, it leaves the `tabs` parameter undefined and does not mention any limitations or effects beyond the enabling action. For a tool with three parameters, this is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no explanation of the parameters. The `chat` parameter is implied as the target, but `tabs` is entirely unexplained, and `enabled` is only implicitly connected to the toggle action. The description fails to compensate for the absence of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'enable/disable forum mode (topics) in a supergroup.' It specifies the action as a toggle and identifies the target as a supergroup. This is specific and distinct from sibling tools that manage topics within an already-enabled forum.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite: 'Requires ≥200 members.' This tells the user when the tool can be used. It does not explicitly contrast with alternatives, but the purpose is unambiguous and the condition is valuable guidance. It lacks an explicit 'when not to use' 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description is not required to restate that. It does add useful constraints like '1 — резерв All' (1 is reserved for All) and implies that updating existing filters is possible, but does not disclose behaviors like whether updates merge or replace existing configurations, or any permission/rate-limit specifics. Thus it adds some but not rich 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with a clear purpose statement followed by a parameter list. Every line provides value, with no waste. The structure is a simple list, which is efficient for 12 parameters, though not particularly elegant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (12 parameters) and presence of an output schema, the description adequately explains all parameters and constraints. However, it misses usage guidelines and behavioral edge cases (e.g., update semantics, error scenarios), leaving some gaps. It is complete enough for basic invocation but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 0%, and the description fully compensates by explaining every parameter. It clarifies that filter_id is a unique ID in the range 2-255 with 1 reserved, included_chats accepts IDs or usernames, and boolean flags auto-include or exclude categories. This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Создать/обновить кастомную папку диалогов' (Create/update custom dialog folder), providing a specific verb and resource. This clearly distinguishes it from sibling tools like get_dialog_filters and delete_dialog_filter, which are listed in the 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool's function (create/update) but gives no explicit guidance on when to use it versus alternatives. No mention of exclusions, prerequisites, or references to sibling tools for listing or deleting filters. The usage context is implied but not stated.
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?
Annotations indicate readOnly=false, but the description adds valuable behavioral details: download_dir path validation, inline returns Image/Audio with a 1 MB limit, and thumb_index downloads only previews. These go beyond what annotations provide, though it doesn't mention side effects like file writing explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a brief summary and a well-structured Args list. Every sentence adds value, and the format is easily scannable. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers key behavioral aspects (inline, thumbnails, path validation) and the output schema handles return values. However, it's ambiguous whether 'media' means all media or a single media, and the required params (chat, message_id) are not described. This leaves moderate gaps for a tool with 5 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 documents three parameters (download_dir, thumb_index, inline) with meaningful semantics, but omits the two required parameters (chat, message_id), leaving a gap. The provided meanings are clear and useful, but not complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Download media from a message' (Скачать медиа из сообщения), which is a specific verb+resource. This distinguishes it from sibling tools like download_profile_photo and get_media_info, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. It doesn't mention any exclusions or alternative tools. The parameter hints provide some usage context but not tool-selection 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?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds the source scope ('feed by subscriptions') but does not disclose potential pagination, ordering, or whether already-viewed stories are included. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence in Russian that is front-loaded and free of unnecessary words. It directly conveys the tool's purpose without elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, strong annotations, and an existing output schema), the one-line description is sufficient to set expectations. Minor ambiguity remains around the term 'available' (e.g., active stories vs. archive), but the output schema likely clarifies the structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is fully covered and leaves nothing to explain. The description adds no parameter information, but none is needed; the baseline of 4 for zero-param tools applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool retrieves all available stories from the user's feed, scoped by subscriptions. This clearly identifies the resource and scope, distinguishing it from sibling story tools like get_peer_stories (specific peer) and get_stories_by_id (specific IDs), though it doesn't name them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a use case: fetching the aggregate stories feed from all subscriptions. However, it provides no explicit guidance on when to prefer this over alternatives like get_peer_stories or get_stories_archive, leaving the agent to infer context from sibling names.
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?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds only 'by geo' and 'for optimization', which is some context but does not disclose return format or edge cases. No contradiction with annotations is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that conveys the core purpose without any filler. It is front-loaded and appropriately sized for a zero-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters) and the presence of a full output schema plus rich annotations, the description is complete enough for its purpose. It states the core function, though it is sparse and does not elaborate on output specifics, which are likely covered by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema fully covers parameter semantics by default. The description does not need to add parameter details, and the baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the nearest Telegram DC based on geo, which is specific and distinguishes it from sibling tools. However, it is phrased as a noun phrase rather than an explicit verb+resource construction, so it falls short of 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions it is 'used for optimization', providing a light usage context. It does not explicitly state when to use this tool versus alternatives or exclude cases, making it 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool is known to be a safe read operation. The description adds useful context that only messages not yet sent are returned, which goes beyond the annotations. It does not disclose other behavioral traits such as pagination, ordering, or potential errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the core purpose. It is front-loaded with the key action and resource, and contains no redundant or extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with one parameter and an output schema, the description provides the essential purpose and the key filter (only unsent scheduled messages). It does not mention pagination, sorting, or result details, but these may be covered by the output schema. Overall, the description is sufficiently complete for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter 'chat' with 0% description coverage. The description mentions 'в чате' (in the chat), which provides a hint that the parameter refers to the chat context, but it does not clarify the expected format (e.g., chat ID vs. username) or any constraints beyond what the schema's anyOf integer/string shows. This 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Список отложенных сообщений в чате' (List of scheduled messages in the chat), specifying the action (list) and the resource (scheduled messages). The qualifier '(которые ещё не отправлены)' (which have not been sent yet) adds specificity and distinguishes it from sibling tools like send_scheduled_now or delete_scheduled.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied: use this tool when you need to list unsent scheduled messages in a chat. However, there is no explicit guidance on when to use it versus alternatives like get_history or search_messages, nor any exclusions or conditions.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds context about what versions are included (Claudegram, Telethon, MCP SDK) but does not disclose additional behavioral traits like rate limits or authentication. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a highly concise single phrase that conveys the essential meaning without any waste. For a no-argument getter, this is appropriately sized and front-loaded, earning a 5 for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, has no parameters, strong annotations, and an output schema is present, so return values are likely covered. The description specifies the component versions, making it complete enough for an agent to understand the expected response. No additional detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema description coverage is vacuously 100%. The rubric sets a baseline of 4 for 0-parameter tools, and the description adds no parameter-specific meaning since none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Версия Claudegram + Telethon + MCP SDK' clarifies that the tool returns the version of these three components, which distinguishes it from other tools and gives specific meaning to the get_server_version name. It is clear but lacks an explicit verb, being a noun phrase rather than a full sentence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not state when to use this tool or mention alternatives, but the tool is a zero-parameter getter, making its usage obvious. There are no sibling tools with a similar purpose, so the usage is implied rather than explicitly guided.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by explaining the meaning of inbound/outbound/ascending parameters and contextualizing the data as purchases/expenses. It does not mention return format or rate limits, but with output schema present and read-only hints, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one line for purpose and three bullet-like argument definitions. Every sentence adds value with no redundancy or fluff. It is front-loaded with the main purpose and then parameter details, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only transaction history tool with an output schema and strong annotations, the description covers the essential semantic details. It is complete enough for an agent to understand the tool's function and key parameters. The omission of limit semantics is minor and does not hinder effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 inbound ('only refills'), outbound ('only debits'), and ascending ('old first') in plain language, covering 3 of 4 parameters. The 'limit' parameter is not described, but it has a default value in the schema and is straightforward. Overall, the description adds meaningful semantics beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as 'История Stars-транзакций' (history of Stars transactions) with a parenthetical about purchases/expenses. It distinguishes the tool from siblings like get_stars_balance by focusing on transaction history rather than balance. However, it lacks a strong verb (e.g., 'retrieves' or 'lists'), so it is clear but not maximally explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives. It does not mention any exclusions or explicitly state a preferred use case. The purpose is implied by the tool name and description, but there is no direct comparison to sibling tools like get_stars_balance.
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?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only the scoping behavior (global or chat) and does not mention other behavioral traits like return format, pagination, or rate limits. It adds some value but not rich 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core purpose and scope. There is no filler or redundant information, and it is appropriately sized for a simple search tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema and annotations present, the description provides essential scope information but omits nuances like pagination, filtering options, or how 'globally' differs from other search tools. It is adequate for a straightforward search but has clear gaps in behavioral and parameter detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 undocumented parameters. It clarifies 'query' via 'по тексту' and 'chat' via 'глобально или в чате', but leaves 'limit' and 'from_user' without added semantic explanation. Partial compensation only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Поиск' (search), identifies resource 'сообщений' (messages), and clarifies scope 'глобально или в чате' (globally or in a chat). This distinguishes it from sibling tools like search_global by specifying where the search applies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for text-based message search with optional chat scoping, but it does not explicitly state when to use this tool versus alternatives like search_global or get_history. It gives context that the search can be global or chat-scoped, but lacks exclusion criteria or alternative recommendations.
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?
The description discloses that the caption is applied only to the first media item, which is non-obvious and not covered by annotations. It also states the size limit of 2-10 items, adding behavioral context beyond the basic annotation flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences; the first states the core purpose, the second adds a crucial behavioral detail. No redundant or unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters and no schema descriptions, the description covers only album size and caption behavior. It lacks guidance on chat identifier format, file path requirements, and other parameters, making it insufficient for correct invocation in many scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 chat, file_paths, silent, or reply_to parameters. It only clarifies caption placement, leaving most parameter semantics undefined and forcing the agent to infer from types alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Send an album of 2-10 photos/videos as one group', specifying the verb, resource, and constraints. This distinguishes it from sibling tools like send_message and send_file which handle single media/text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when sending 2-10 media files as a group, but it does not explicitly mention alternatives or when-not-to-use. The caption note adds context but no direct guidance on tool selection.
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?
Annotations already flag readOnlyHint=false, indicating a write operation. The description adds no further behavioral detail (e.g., whether the sticker set remains available for reinstall, or if any confirmation is needed). It does not contradict annotations, so score remains at baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that conveys the core action without excess. It is as concise as possible while still being informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter), presence of annotations, and an output schema, the description covers the essential operation. However, it lacks contextual details like how to obtain a sticker set's short_name, which would make it fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 'short_name' parameter. It is unclear what format is expected or where to obtain it. With only one required parameter, the description should have provided at least a hint about its semantics, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (remove/uninstall) and the target resource (sticker set) from the account. It distinguishes from sibling tools like 'install_sticker_set' and 'get_installed_stickers' by its explicit 'remove' semantic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when removing an installed sticker set, but offers no explicit guidance on when to use versus alternatives, nor any prerequisites such as already having the sticker set installed. The contrast with 'install_sticker_set' is only contextual, not stated.
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?
Annotations already declare destructiveHint=true and idempotentHint=false, so the description only needs to add context. It adds the permanence and irreversibility ('won't be able to return'), which is valuable behavioral context. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence with no filler, fully front-loaded and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The purpose and permanence are clear, but the description lacks information about prerequisites, parameter semantics, and explicit relationship to sibling tools. It's adequate for a simple ban action but leaves ambiguity for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no parameter details, and the schema has 0% description coverage. 'chat' and 'user' are ambiguous (accept integer or string), and the description doesn't clarify what identifiers are expected, so it adds no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (ban a participant), the permanence (forever), and the consequence (cannot return), which distinguishes it from temporary kicks or restrictions. The verb and resource are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for permanent bans via 'forever', but does not explicitly mention when to use it over alternates like kick_participant or restrict_participant. No exclusions or alternatives are provided.
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?
The annotations already indicate destructive behavior, but the description adds meaningful context: blocking prevents the user from writing and explains the story-blocklist behavior with my_stories_from=True. This goes beyond the annotations and provides behavioral transparency about the tool's 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using only two sentences. It leads with the core action and consequence, then briefly covers the parameter nuance. No wasted words; the structure is clear and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple nature (2 params, output schema exists, annotations provided), the description is adequate but has gaps. It does not explain the 'user' parameter format, the full scope of blocking vs. story-only, or mention that unblock_user reverses this action. It covers the main behavior but leaves room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage (0%). The description explains only the 'my_stories_from' parameter (story-blocklist nuance) but fails to clarify the required 'user' parameter, which remains ambiguous in terms of format or semantics. With low schema coverage, the description should compensate more but falls short.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb and resource: 'Заблокировать пользователя' (Block user) and specifies the consequence ('он не сможет писать' – he won't be able to write). This distinguishes it from related tools like unblock_user and ban_participant, 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating the blocking effect, but it does not explicitly mention when to use it versus alternatives (e.g., unblock_user, ban_participant). The nuance about my_stories_from is a usage hint for a specific scenario, but overall guidance is minimal.
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?
Annotations already disclose the destructive nature (destructiveHint=true) and non-idempotency (idempotentHint=false). The description adds the useful context that this operates only on messages before sending, which is a behavioral constraint. However, it does not elaborate on permanence, effects on multiple chats, or confirmation requirements beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and includes a helpful qualifier. There is no extraneous information or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple operation, the presence of an output schema, and destructive annotations, the description is minimally adequate. However, it lacks parameter semantics and prerequisites (such as how to obtain scheduled message IDs), leaving gaps for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about the 'chat' or 'message_ids' parameters. While 'message_ids' can be inferred as scheduled message IDs from the tool's purpose, the 'chat' parameter is ambiguous (which chat? integer or string?). The description fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('delete') and the resource ('scheduled messages') with a temporal qualifier ('before they are sent'). This distinguishes it from the sibling tool 'delete_message' which likely targets sent messages, 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'before they are sent' provides clear temporal context for when to use this tool (for canceling unsent scheduled messages). While it doesn't explicitly name alternatives or exclusions, the context is effective and implies that this is not for deleting already-sent messages.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful behavioral context by warning that the response is raw JSON with many keys requiring search by name, which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, the first stating the resource and the second setting expectations about the raw JSON output. Every word adds value, with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool with an output schema available, the description fully captures what the agent needs: it identifies the resource, lists example contents, and indicates the response format. Nothing important is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters since there are none, and this is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns client configuration (feature flags, premium limits, gifts) and mentions the raw JSON output. This makes the tool's purpose evident, but it doesn't explicitly distinguish it from sibling tools like get_telegram_config, so it lacks some differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. The description implies it's for retrieving client config, but it doesn't state when it should be used over similar tools or when it shouldn't be used, leaving usage 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context about viewer scale (1000+ viewers) and explains the two behavioral filters (just_contacts and reactions_first) that affect output, going beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a clear one-line purpose followed by a compact args list. Every word adds value, and the structure is front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with strong annotations and an output schema, the description covers the key behavioral filters and purpose. It lacks an explicit explanation of limit, but schema defaults and obvious naming mitigate this; overall the description is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains just_contacts and reactions_first, adding meaning beyond the raw schema. However, it omits limit and story_id, and with 0% schema description coverage, this is only partial compensation for the parameters that need clarification.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Кто посмотрел мою story' clearly states the tool returns the viewers of a story. It uses a specific verb+resource structure and distinguishes itself from sibling story tools by focusing on views rather than story content, sending, or archiving.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives or when not to use it. The intended usage is only implied by the tool name and purpose, with no reference to sibling tools 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?
Annotations already indicate this is a mutation (readOnlyHint=false), so the description does not need to restate that. It adds value by explaining the clear_mentions parameter and that max_id=0 means 'all', but it does not disclose side effects such as changes to unread counters or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a one-line purpose statement followed by a compact parameter list. Every word contributes information, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple state-change tool, the description covers the core purpose and parameter semantics. An output schema exists, so return value details are not needed. The main gap is the lack of usage guidance, but that is covered under a separate dimension; within itself, the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no field descriptions (0% coverage), so the description carries the burden. It explains max_id ('up to which id, 0 = all') and clear_mentions ('also reset @mentions'), which goes beyond the schema's default values. The chat parameter is left unexplained, but its meaning is fairly inferable from the tool name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Mark chat messages as read' (Пометить сообщения чата прочитанными), identifying a specific action and resource. It distinguishes itself from the sibling tool mark_stories_read by focusing on chat messages, and the optional clear_mentions behavior adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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, no exclusions, and no context about prerequisites or side effects. It only lists parameters, leaving the agent to infer the usage context from the name alone.
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?
Annotations already declare the tool as readOnly, idempotent, and non-destructive. The description adds that the search is global and matches by name or @username, which is additional behavioral context. However, it does not disclose nuances like partial matching, pagination, or result ordering, so the added transparency is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core purpose without unnecessary words or repetition. Every word contributes meaning, making it an exemplar of conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward search tool with two parameters and an output schema, the description covers what is searched and by what criteria. The absence of limit details is a minor gap, but the parameter name and default make it self-explanatory. Overall, the description is complete enough for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since the input schema has no parameter descriptions (0% coverage), the description must compensate. It explains that 'query' is a name or @username, giving that parameter clear semantics. However, 'limit' is left unexplained; its purpose (max number of results) is only implied by its name and default value, leading to incomplete compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('global search'), the resource type (users/chats/channels), and the search criterion (name or @username). This distinguishes it from sibling tools like search_messages (which searches message content) and resolve_username (which resolves exact usernames), 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finding peers by name or username but does not explicitly state when to prefer this tool over alternatives like resolve_username or search_messages, nor does it mention any exclusions or prerequisites. The context is clear but there is no explicit guidance on alternative selection.
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?
The description adds useful behavioral context beyond the annotations, such as Telethon auto-detecting the file type, voice_note requiring .ogg/.mp3, and ttl_seconds being PM-only. This enriches the agent's understanding of side effects and constraints, though it doesn't cover potential errors or upload behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-line purpose followed by a clear bulleted parameter list. It is appropriately sized for 13 parameters, with each bullet earning its place. Slightly verbose but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's core function and all parameters, including behavioral nuances. Because an output schema exists, missing return details are not critical. It lacks explicit error handling or upload progress details, but overall it's sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only titles and types with no descriptions, while the description explains every parameter's meaning and constraints (e.g., force_document, voice_note, ttl_seconds). This is a complete and valuable addition beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Отправить файл' (send file) and specifies that Telethon will auto-determine the type. While it is a specific verb+resource, it does not explicitly distinguish itself from sibling tools like send_voice or send_video_note, which are more specialized.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like send_voice, send_video_note, or send_album. The description only explains the tool's own parameters, not the appropriate context for choosing it over 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?
The description discloses meaningful behavioral details beyond annotations: it specifies the input format (.mp4), automatic conversion to a round video, and hard limits (≤60s, 384px diameter). This is useful context that helps the agent anticipate constraints, though it does not mention error handling or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and key constraints. Every word 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (5 parameters, output schema present), the description covers the core concept but omits operational details such as file path prerequisites, failure modes, or how the output schema is populated. It is minimally adequate, but leaves room for ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description was expected to compensate for undocumented parameters, but it only mentions video constraints and ignores 'chat', 'file_path', 'silent', 'reply_to', and 'duration_seconds'. While parameter names are partially self-explanatory, key semantics like how 'duration_seconds' interacts with the 60s limit remain unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('send') and the specific resource ('video-note'), and adds precise technical constraints (.mp4 input → round video ≤60s, 384px diameter). This unambiguously distinguishes it from sibling tools like send_file or send_voice.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for sending video notes, but it does not explicitly state when to prefer it over alternatives like send_file or send_voice. No exclusions or alternative tool references are provided, so usage guidance remains implicit rather than explicit.
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?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds minimal extra context by noting the tool retrieves fields like is_pinned/unread in a batch, but it doesn't describe return format, pagination, or other behaviors. With annotations present, 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the core function, and the second provides a practical use case. There is no redundancy or filler, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read-only batch operation with strong annotations and an output schema, so return values need not be described. However, the lack of explanation for the 'compact' parameter leaves a gap. Overall, it is mostly complete for selecting and invoking correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 implicitly maps chat_ids to 'N конкретных диалогах' but gives no details about the 'compact' parameter (boolean, default true) or how chat_ids are interpreted beyond the schema. This is insufficient for a 0% coverage tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('get information') and resource ('N specific dialogs') in one call, distinguishing it from siblings like list_chats or get_chat_info by its batch and ID-based nature. The mention of checking is_pinned/unread further clarifies its focused 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit use case: 'полезно для batch-проверки is_pinned/unread перед массовой операцией' (useful for batch-checking is_pinned/unread before a mass operation). This gives clear context for when to use the tool, but it does not mention exclusions or explicitly name alternatives like get_chat_info.
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?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds the scoping behavior 'across all chats' (no chat filter) and 'unsaved' drafts, which provides some behavioral context beyond annotations, but lacks details like pagination or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that conveys the essential purpose without redundancy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, an output schema, and annotations covering safety, the description is complete for a simple getter tool. It clearly states what the tool returns (list of drafts) and the scope (all chats).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and schema coverage is 100%, so the description need not explain parameter details. The baseline for 0-parameter tools is 4, and the description appropriately doesn't add unnecessary parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Список несохранённых черновиков по всем чатам' (List of unsaved drafts across all chats) clearly states the tool's function with a specific verb ('list') and resource ('drafts'), and distinguishes it from sibling mutation tools like save_draft or clear_draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. It is a single declarative sentence with no mention of exclusions, prerequisites, or related tools.
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?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds the context that results are 'current' (i.e., a live snapshot) and specifies the content as vote counts per option, which is useful beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly conveys the tool's purpose and return value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only retrieval tool with good annotations and an output schema, the description is largely sufficient. It states what the tool returns, though it could mention that the message must be a poll or how errors are handled. The output schema likely covers return structure, so this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has only field titles 'Chat' and 'Message Id' with zero description coverage. The tool description does not explain the parameters further, though it implies message_id refers to a poll message. This is minimal compensation 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns current poll results with vote counts per option. It uses a specific noun phrase that distinguishes it from sibling tools like vote_poll and send_poll. The parenthetical adds concrete detail about the data returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended usage is implied by the name and description—retrieve results for a poll identified by chat and message_id. However, there is no explicit guidance on when to use this versus alternatives (e.g., vote_poll, send_poll) and no exclusions or prerequisites are mentioned.
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?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds the behavioral detail that only metadata is returned, not the image itself, and explains the offset/max_id filtering semantics. This adds some value beyond annotations, but is not richly 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose, one for scope qualification, and a short bullet list for the two explained arguments. No filler, efficient structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 4-parameter schema, the description covers only offset and max_id, omitting chat and limit. The output schema exists, so return values are covered elsewhere, but the parameter gaps and lack of usage notes leave the agent partially informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 explains offset and max_id with semantic meaning, but leaves chat and limit unexplained beyond their schema defaults. This is partial compensation, not full.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists profile photos (metadata only) for users/groups/channels, using a specific verb 'list' and resource 'profile photos'. It also explicitly notes 'without downloading', which distinguishes it from the sibling tool download_profile_photo.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you need profile photo metadata without downloading the actual images. It does not explicitly name alternatives or provide 'when-not-to-use' guidance, but the 'без скачивания' clause clearly sets the boundary against downloading tools.
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?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds valuable context that the destructive action is reversible (the participant can return), which is not disclosed by annotations alone. This goes beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no fluff. It is front-loaded with the core action ('Kick') and includes an important qualifier. However, it is somewhat under-specified, which slightly reduces the score from a perfect 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple kick operation, and the description covers the essential behavior (temporary removal). The existence of an output schema reduces the need for return details, but the description omits important context such as required permissions, error conditions, or side effects. It is minimally viable but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description does not elaborate on the 'chat' and 'user' parameters. It does not clarify whether these accept IDs, usernames, or both, nor how the system resolves them. The description fails to compensate for the lack of schema-level descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action (kick) and resource (participant from chat), and adds a distinguishing behavioral detail ('they will be able to return'), which differentiates it from the sibling tool ban_participant. This makes the tool's 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool vs. alternatives by noting the kicked user can return, suggesting a temporary removal distinct from a permanent ban. However, it does not explicitly name alternatives or provide WHEN-NOT guidelines, so it slightly 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?
Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds that the tool returns info plus id, but doesn't disclose behavior for invalid or missing usernames, nor any rate limiting. Minimal additional context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that immediately conveys the purpose and return value. No superfluous words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter), strong annotations, and the presence of an output schema, the description is nearly complete. It could mention error cases or what 'info' includes, but the core functionality is well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does 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 mentions '@username', which hints at the expected format but does not clarify whether the '@' symbol should be included or provide any other semantic detail about the parameter. The added meaning is minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('find entity') and the resource ('by @username'), and specifies what is returned ('info + id'). This distinguishes it from sibling tools like get_full_user or get_input_peer, which operate on already-resolved entities or IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a username and need the corresponding entity/id. It doesn't explicitly mention alternatives or exclusions, but for a simple resolver, the intended context is reasonably clear.
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?
The description adds a useful behavioral detail: the tool converts .ogg/.mp3 files to an opus voice note, which goes beyond the annotations. It aligns with readOnlyHint=false, confirming a mutating operation, and does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core purpose and key format detail without any waste. It is easy to parse and perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's moderate complexity with 6 parameters, the description captures the essential function and format conversion. The presence of an output schema covers return values, and the schema itself lists parameters. The description is reasonably complete for a sending tool, though it lacks some contextual details about optional parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should compensate by clarifying parameters. It only hints at the file format for file_path, leaving chat, silent, caption, reply_to, and duration_seconds unexplained. The minimal value added over the schema is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'send a voice message' and specifies the format conversion (.ogg/.mp3 → opus voice note), distinguishing it from generic file sending tools like send_file. It unambiguously identifies the resource and operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for sending voice messages but does not explicitly state when to choose this over send_file or send_video_note. No exclusions, alternatives, or contextual conditions are mentioned, leaving the agent to infer.
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 adds detail about the 'offline' parameter, explaining that it toggles the green online indicator. However, it does not disclose other behavioral aspects such as authentication requirements or the effect of setting offline to false, and relies on annotations for mutation semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear purpose statement and a parameter explanation. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description covers the essential operation and parameter meaning. It doesn't discuss the online=true case explicitly but it's easily inferred. The presence of an output schema further reduces the need for return-value documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'offline' is explicitly explained in the description with a concrete behavioral consequence (hiding the green 'online' circle). This 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: setting the user's online/offline status. It uses a specific verb and resource, and it distinguishes itself from sibling tools by focusing on presence status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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, nor any context for its use. The description only states what the tool does and explains the parameter, but offers no usage direction.
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?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating a safe, non-mutating operation. The description adds valuable behavioral context beyond the annotations by specifying the return behavior: it returns either full text or a partial transcription with a pending flag, and notes the Telegram Premium requirement. This gives the agent a better understanding of possible 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences in Russian, front-loaded with the primary action. Every word earns its place: the main function, the Premium caveat, and the return behavior. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the output schema, and the annotations, the description is mostly complete. It covers the purpose, the premium requirement, and the possibility of a partial transcription with a pending flag. However, it does not mention any prerequisites or error conditions (e.g., the message must contain voice), but these are reasonably implied by the tool name and description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description provides no explanation of the 'chat' and 'message_id' parameters. While the names are somewhat self-explanatory, the description does not compensate for the lack of schema documentation. It does not clarify types, formats, or how to identify the message to transcribe, so the agent must infer semantics from the parameter names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Transcribe voice to text' (Транскрибировать голосовое в текст). It identifies the specific action (transcribe), the resource (voice/audio), and the output format (text or partial transcription). This distinguishes it from all sibling tools, none of which offer transcription functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions that this is a Telegram Premium feature, which is a usage constraint, but it does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. Since there are no direct sibling tools for transcription, the context is clear but the guidance is minimal.
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?
The description adds constraints beyond the annotations, such as requiring exact text match and the XOR relationship between button_text and button_index. However, it does not disclose the side effects or outcomes of clicking the button, though annotations already indicate the operation is not idempotent and not 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence summary followed by a minimal arg list. Every sentence adds value, with no redundant or filler content. It is properly front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential behavior and parameter constraints for the tool. Given the existence of an output schema and annotations, it does not need to explain return values or safety. It could be improved by clarifying the roles of chat and message_id, but those are reasonably inferable from the summary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining the meaning and constraints of button_text and button_index, including the flat-index interpretation and the requirement to pass exactly one of them. It does not explain chat and message_id, but those are standard parameters whose purpose is clear from their names and the tool context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Нажать inline-кнопку под сообщением бота' (click an inline button under a bot message), specifying both the verb and the target resource. It distinguishes the tool from siblings by focusing on inline button interaction, which is unique among the provided tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives, nor does it mention exclusions or conditions. The usage context is only implied by the tool name and summary, leaving the agent to infer 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?
The description adds valuable behavior beyond the annotations: explains two output modes (inline as base64/ImageContent vs. writing to file and returning a path), the size options (640x640 or 160x160), and the inline size limit (≤1 MB). No contradiction with the annotations (readOnlyHint=false is consistent with file writing).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single purpose sentence followed by a short argument list. Every sentence adds necessary detail, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with an output schema, the description covers the key behavioral aspects: output modes, file vs. inline, and size variants. It does not explain the chat parameter format or download_dir purpose in detail, but these are reasonably inferable. The output schema exists, so return values need not be detailed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage, so the description must compensate. It does explain download_big and inline with specific meanings and sizes, but chat and download_dir are not described beyond their schema names. Partial compensation, with two of four parameters getting meaningful semantic detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (download), resource (avatar/profile photo), and target (user/chat), and distinguishes it from sibling tools like get_profile_photos (which lists photos) and download_media (generic media download). The mention of 'to disk or inline (base64)' adds scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains parameters and output modes, but does not explicitly state when to use this tool versus alternatives like get_profile_photos or download_media. Usage is implied by the description of the tool's function, but no explicit when/when-not guidance is 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?
Annotations already declare readOnlyHint and idempotentHint, covering safety. The description adds non-obvious behavioral context by revealing that there are two distinct blocklists (story vs main) and that my_stories_from toggles between them. This goes beyond the annotated hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the core purpose and followed by the key parameter explanation. Every word is meaningful and there is no redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with complete annotations and an output schema, the description adequately covers purpose and the least obvious parameter. It lacks pagination details, but those are reasonably inferred from limit/offset and the existing output schema, making it sufficient for this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly explains my_stories_from, which is the most cryptic parameter, adding value beyond the schema. However, limit and offset are left undocumented; while their names and defaults suggest pagination, the description does not confirm this or explain any interaction.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Список заблокированных юзеров' clearly states that the tool returns a list of blocked users. The clarification of my_stories_from (story-blocklist vs main) further specifies scope, and the tool name get_blocked distinguishes it from sibling actions like block_user and unblock_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does 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. Usage is implied by the name and purpose, but the description does not mention exclusions or contrast with other tools. The parameter explanation hints at selecting between story and main blocklists, but no broader context is given.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no extra behavioral context beyond what the name implies; it is essentially a restatement of the tool name, providing no additional 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the essential information. No fluff or redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter read-only list tool with an output schema and strong annotations, the description is sufficiently complete. However, it could mention something about pagination or return value details, though the output schema likely covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description need not explain parameter semantics. Per guidelines, baseline is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'List of installed sticker sets.' It distinguishes itself from siblings like search_sticker_sets and install_sticker_set by targeting only installed sets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for retrieving installed sticker sets, providing context for when to use it. However, it does not explicitly name alternatives or state when not to use it, so it falls slightly 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?
Annotations already declare this as a mutating, non-idempotent, non-destructive, open-world operation. The description adds that the target is a public channel/group and that it can be specified via username or invite link. It does not disclose side effects like becoming a member or duplicate-join errors, but given annotation coverage, this 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and free of filler. It conveys purpose and parameter semantics without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter join tool, the description provides purpose and parameter format. An output schema exists, so return values are not needed. It lacks guidance on when to use and potential failure modes, but overall it is sufficient for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the 'chat' parameter, but the description clarifies that string values are @username or invite links. This is essential for correct invocation. It does not explain the integer alternative, but the primary ambiguity is resolved.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool joins a public channel/group via @username or invite link, using a specific verb and resource. This distinguishes it from siblings like leave_chat, create_group, and auth_submit_code. It also specifies the method of target identification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use guidance or alternatives are provided. The description implies use when the user wants to join a chat, but it doesn't mention exclusions (e.g., private chats) or name leave_chat as the counterpart. Context is clear but minimally developed.
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?
While annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, the description adds value by explaining that the tool returns all dialogs with no filter and that the compact form reduces payload by ~85%. This goes beyond the safety profile to convey scope and a key behavioral nuance. It is not overly detailed but sufficient given the strong annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise and front-loaded. The first line states the tool's purpose immediately, and the additional line about 'compact' is directly relevant. The final pointer to alternative tools is a useful one-liner. There is no fluff; every sentence earns its place, making it an exemplary model of brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, an output schema exists (not shown), and annotations are comprehensive, the description covers the core use case well. However, it falls short on documenting the available filter parameters (archived, only_unread, ignore_pinned, limit) and the default behavior of excluding them. This leaves the agent guessing about how to filter the list, which is relevant for a 'list all' tool with these options. It is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 5 parameters (limit, compact, archived, only_unread, ignore_pinned) with no descriptions, and the overall schema description coverage is 0%. The description only documents the 'compact' parameter (mentioning the lightweight form with ~85% less payload), leaving the other four parameters entirely unexplained. This is a significant gap, as the description must compensate for the complete lack of schema descriptions but only covers 1/5 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists all dialogs (users/bots/groups/channels) without filtering, using a specific verb 'list' and resource 'chats'. It also distinguishes itself from sibling tools by explicitly pointing to list_channels, list_groups, and list_bots for typed lists, satisfying the 'distinguishes from siblings' criterion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: to get an unfiltered list of all chat types. It explicitly names alternatives for typed lists (list_channels, list_groups, list_bots), giving the agent a good sense of when to choose this tool over those. However, it stops short of an explicit 'when not to use' statement or mentioning other alternatives like search_global, so it misses the top 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?
Despite the annotations already indicating non-read-only behavior, the description adds valuable context: Telegram will send a random result, and the allowed emoji values are enumerated. This goes beyond the bare annotations, though it doesn't disclose any prerequisites or response details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: a single-sentence summary followed by a compact argument list. Every sentence provides useful information with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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, the description covers the essential purpose and the main parameter. It omits details about 'silent' but that is a standard boolean flag. Overall, it is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions (0% coverage), but the description clarifies the 'emoji' parameter by listing its accepted values. It does not explain 'chat' or 'silent', which are left to the schema names/types. The description partially compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it sends an interactive 'dice' (кубик), with a specific verb and resource. It distinguishes itself from other send_* tools by describing the interactive random-result behavior and explicitly listing the available emoji options.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose is clear enough to imply when to use it (when you want to send a dice-like interactive message). However, there is no explicit guidance on when not to use it or how it differs from send_message, send_media, or other message-sending 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?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description is not required to restate mutation. It adds useful behavioral context such as option count limits (2-10), quiz mode requirements, and auto-close constraints (5-600 seconds). However, it does not disclose potential side effects like message delivery failures or permission requirements, which would have enhanced 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence followed by a neatly formatted list of parameter explanations. Every line provides actionable information without fluff or repetition of schema types. The structure is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 13 parameters and an output schema, the description covers the vast majority of behavior and constraints. It misses only the silent parameter and does not explicitly restate required parameters, but the schema handles those. Overall, it equips an agent with sufficient knowledge to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The Args list explains most parameters with meaningful constraints and interdependencies (e.g., correct_option_index is 'для quiz=True', close_period_seconds has a 5-600 range). However, it omits descriptions for chat, question, and silent. Chat and question are self-explanatory from schema titles, but silent is not addressed, leaving a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Создать и отправить опрос' (Create and send a poll) uses a specific verb and resource, clearly identifying the tool's action. It distinguishes itself from siblings like vote_poll and get_poll_results, which handle polling but not creation/sending.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a poll needs to be created and sent, but it does not explicitly state when to use it over alternatives or provide exclusions. The context is clear enough but lacks explicit guidance like 'use this to send polls instead of send_message'.
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?
Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds a note about indefinite availability, which provides some behavioral context (e.g., no time limit) but does not elaborate on side effects or reversibility. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence with no filler. The key information (action, resource, audience) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple toggle tool with an output schema, the description covers the essential purpose and scope. It does not mention edge cases or prerequisites, but given the tool simplicity and the presence of an output schema, it is largely complete. The 'available indefinitely' caveat adds a minor, albeit ambiguous, note.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 implies that the 'pinned' boolean controls pin/unpin, and 'story_ids' specifies which stories, but does not explicitly document the parameters or their formats. The parameter names are self-explanatory, but the description adds limited detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Закрепить/открепить мои stories в профиле (доступно бессрочно)' clearly states a specific action (pin/unpin) on a specific resource (my stories in profile). It distinguishes from sibling tools like get_pinned_stories (read-only) and pin_message (for messages).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does 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 the tool: to pin or unpin the user's stories. It does not explicitly mention alternatives or exclusions, but the operation is self-evident and unambiguous among the story-related 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?
Annotations already indicate this is a write operation (readOnly=false) and not idempotent. The description adds the key behavior of unpinning all when message_id is None, which is useful context. However, it does not disclose potential side effects, error conditions, or permission requirements, so it doesn't go far beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with a brief one-line purpose followed by an args block. Every sentence adds essential information, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters, the description adequately explains the main behavior. An output schema exists, so return values are covered there. It could add more about edge cases (e.g., no pinned messages) but is sufficient for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does 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 does explain the message_id parameter and its None meaning, but it does not clarify the 'chat' parameter at all. Since there are 2 parameters and only one is explained, the compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool unpins one or all pinned messages in a chat, using a specific verb and resource. It distinguishes itself from the sibling tool pin_message by explicitly covering the 'unpin' action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use each mode: if message_id is specified, unpin that message; if None, unpin all pinned messages. It doesn't explicitly mention alternatives or exclusions, but the context is sufficiently clear for a single-purpose 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?
The description adds specific behavioral detail beyond the annotations: it enumerates the mutable fields (title, closed, hidden) and clarifies that 'hidden' only affects the header for the General topic. This complements the annotations' generic mutation flags with concrete operation semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with the first sentence carrying the primary purpose and the second sentence adding a critical constraint on the 'hidden' parameter. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters, 2 of which are required, and an output schema. The description covers the main behaviors but omits any mention of the required parameters or the 'icon_emoji_id' field. It is minimally adequate for the core use case but not fully complete for all possible invocations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining the 'title', 'closed', and 'hidden' parameters through the action verbs. However, it leaves 'chat', 'topic_id', and 'icon_emoji_id' entirely unexplained, so the compensation is only partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('редактировать' = edit) and resource ('тему' = topic), and specifies the main actions: rename, close, hide. This distinguishes it from sibling tools like create_forum_topic or delete_forum_topic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context for using the hidden parameter—only valid for the General topic (id=1)—which is actionable guidance. However, it does not mention alternatives or when not to use the tool, so it stops short of a full 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?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context by stating that the return value is a dict with an underscore key that is meant for 'kwargs_json' in invoke_raw calls. This reveals output structure and integration, which is beyond what the annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, with the purpose front-loaded and the return usage following immediately. There is no filler or repetition; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only utility with an output schema and clear annotations, the description covers the essential purpose and return integration. However, the lack of parameter clarity prevents a perfect score, as the agent might not know what exactly to pass for 'chat'. Overall, it is complete enough for a low-complexity helper tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the 'chat' parameter, and the description only says 'для чата' (for chat) without explaining the accepted formats (e.g., numeric ID, username, or both). With the schema allowing integer or string, the ambiguity is unresolved. The description does not sufficiently compensate for the missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Получить InputPeer для чата' (get InputPeer for a chat), which identifies both the action and the resource. It also distinguishes this from sibling tools by specifying that it is needed for raw API calls, setting it apart from higher-level tools like get_chat_info or resolve_username.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says the InputPeer is 'нужен для raw API вызовов' (needed for raw API calls) and that the result can be placed into 'kwargs_json for invoke_raw'. This gives clear usage context and ties it to a sibling tool. It does not explicitly list alternatives or exclusions, but the raw-API anchor 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds no further behavioral context, but it does not contradict the annotations and the tool's simplicity reduces the need for additional 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that fully conveys the tool's purpose. It is appropriately sized for a simple zero-parameter operation and is instantly parsable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the presence of annotations, and an output schema, the description sufficiently frames the operation. No additional information about return values or conditions is necessary because the output schema covers that aspect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema imposes no burden. According to the rubric, a baseline of 4 applies, and the description need not document parameters since none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Information about the current authorized user' clearly identifies the resource (current user) and the intent (retrieve info). It distinguishes itself from siblings like get_full_user by specifying 'current' and 'authorized', making the tool unambiguous despite the lack of an explicit verb, which is implied by the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus alternatives like get_full_user or get_authorizations. However, the description and tool name clearly imply usage when the current authorized user's information is needed, so the usage is 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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the context that Stars are an internal currency, which is useful but not deeply behavioral.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys essential meaning without waste. It is appropriately sized for a zero-parameter read-only tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, an output schema exists, and the description is complete enough for an agent to know what the tool does. No further context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters (schema is empty), so there is no parameter semantics beyond what the schema trivially provides. Baseline of 4 applies due to zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the current balance of Telegram Stars, with the added context that Stars are an internal currency. This distinguishes it from the sibling tool get_stars_transactions, which handles transaction history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to check the current Stars balance, but it does not explicitly mention when to use it over alternatives like get_stars_transactions. The usage context is minimal but not misleading.
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?
Annotations already indicate readOnlyHint=false, consistent with an import operation. The description adds the key input requirement (phone numbers without Telegram-ID), but does not disclose what happens on duplicates, whether it overwrites existing contacts, or any failure behavior. More context would be valuable 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: first states the purpose, second defines the argument structure. No filler, front-loaded, and every word contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk import tool, the description gives the core purpose and input format, but lacks details on handling of existing contacts, phone number format, or result/error behavior. The existence of an output schema helps with return values, but the behavioral gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only says contacts is an array of objects with string properties, and coverage is 0%. The description compensates by specifying the intended keys ('phone', 'first_name', 'last_name'), providing essential meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('импорт') and resource ('контакты') with a clear method ('по номерам телефона'), and explicitly differentiates from siblings by noting it does not require Telegram-ID, distinguishing it from add_contact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the bulk import scenario and the condition of phone-based contacts without Telegram IDs. While it doesn't explicitly name alternative tools, the context of 'массовый' and the mention of phone numbers effectively communicates when to use it vs. single-contact 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?
Annotations already indicate a write operation (readOnlyHint=false). The description adds parameter-level behavior (e.g., period_seconds values, pinned effect) but does not disclose broader consequences like post visibility, rate limits, or the need to have media accessible. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact paragraph plus an Args list. It front-loads the purpose and uses bullet-point-style entries for each parameter, with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 6-parameter complexity and zero schema descriptions, the description covers all parameter semantics and the primary action well. It does not mention usage context or edge cases, but an output schema exists so return values are not required. The tool is adequately specified for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description provides essential semantics for all 6 parameters, including allowed values for period_seconds (21600/43200/86400/172800), privacy options, and explanation of pinned and noforwards. 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Опубликовать новую story' (publish a new story) and specifies it handles photo/video. This distinguishes it from sibling story tools like get_* or delete_stories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this versus alternatives. The purpose is implied by the name and the verb 'publish', but no exclusions or alternative tools are mentioned. It relies on the agent to infer that this is the only tool for creating stories.
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?
Annotations already convey that this is not read-only, not idempotent, and not destructive. The description adds behavioral context by explaining the 'chat' parameter default ('None = личный чат с ботом') and clarifying the action as sending /start. However, it does not disclose potential side effects (e.g., whether the bot must already exist, or if repeated calls have different effects), so it only partially adds value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single purpose line followed by a concise, structured argument list. Every sentence serves a purpose, with minimal fluff. It is front-loaded with the action and quickly enumerates parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with three parameters and an output schema, the description is largely complete. It covers all parameters and the core action. It could arguably mention prerequisites or edge cases (e.g., bot not found), but the combination of annotations, schema, and description is sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameter descriptions, so the description carries full responsibility. It explains each parameter clearly: 'bot' as id/@username, 'chat' as destination with None meaning private chat, and 'start_param' as the deep-link payload. This adds substantial meaning beyond the bare schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Запустить бота (отправить /start) с deep-link параметром' (start a bot by sending /start with a deep-link parameter). This is a specific verb+resource combination, distinct from other messaging tools like send_message. The inclusion of the deep-link aspect further sharpens 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied: it's for starting a bot via /start, which is clear from the description. However, there is no explicit guidance on when to use this tool versus alternatives (e.g., send_message to interact with a bot) or any exclusions. The description focuses on what it does rather than when to choose it.
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?
The description adds context beyond annotations by specifying the target folder (folder=0), which clarifies the effect. Annotations already indicate this is a non-read, non-destructive operation. The description does not contradict annotations and provides a small but useful behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that immediately conveys the tool's purpose and key detail (folder=0). It is front-loaded and contains no unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema and annotations, the description is mostly complete. It states what the tool does and the target folder. However, it does not mention prerequisites (e.g., the dialog must be archived) or behavior when the dialog is already unarchived, but these are minor gaps given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'chat' with no description (0% coverage). The description does not explicitly explain what this parameter represents, though it is inferable from the tool name. This is insufficient compensation for the lack of schema documentation, leaving the agent to guess the parameter's exact format and meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Вернуть диалог из архива в основной список (folder=0)' (Return dialog from archive to main list). It uses a specific verb (unarchive/return), identifies the resource (dialog), and distinguishes it from the sibling archive_dialog by explicitly specifying the direction (from archive to folder=0).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context: this tool is for undoing archiving and moving a dialog back to the main list. It does not explicitly mention alternatives, but the context is clear enough given the sibling tool archive_dialog and the direction stated in the description. No exclusions are provided, but none are critical for this simple operation.
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?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by noting it requires no payload and makes only a single request, which gives useful insight into API call efficiency beyond what annotations convey. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short lines. The first line states the tool's essence and key characteristics, the second lists the return fields. Every word adds value, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 does not need to detail return values. It lists the returned counters anyway, which is helpful. It lacks explicit failure modes or limitations, but for a simple read-only stats tool, the context is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is fully covered automatically. The description explicitly states 'без payload' (no payload), reinforcing that no input is required. This meets the baseline for zero-parameter tools and adds clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns dialog counters by type, with a specific list of fields (total, pm_users, bots, etc.). It distinguishes itself from sibling tools like list_chats and get_dialogs_by_ids by focusing on aggregated counts rather than raw dialog data, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies efficient usage ('without payload, 1 request') and lists what it returns, but it does not explicitly state when to prefer this tool over alternatives like list_chats or get_stats. No exclusions or alternative tool mentions are provided, so usage context is only implied.
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?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral details such as default ordering, pagination semantics, and the difference between scheduled and sent messages, which goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: one line for the core purpose followed by a compact list of parameter explanations. Each line earns its place, with no redundant content. The parameter list is easy to scan and directly useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters) and that an output schema exists, the description covers all parameters and their nuances, including edge cases like 'ids' bypassing pagination and 'scheduled' for planned messages. It provides complete operational context without needing to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining every parameter: limit range (1-200), offset_id pagination, min_id/max_id boundaries, from_user filtering, reverse ordering, ids without pagination, reply_to threads, filter_type allowed values, and scheduled flag. This adds substantial meaning beyond the schema's raw types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns chat messages with a default new-to-old ordering. It identifies the specific resource (chat history) and default behavior, but does not differentiate from the sibling tool get_history_with_links, so it lacks sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving chat messages with various filters and pagination, but it does not explicitly state when to use this tool versus alternatives like search_messages or get_history_with_links. No exclusions or alternative tool references are provided.
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?
Annotations already indicate a safe read-only, idempotent operation. The description adds value by specifying the return payload: set metadata plus first 10 stickers with id and emoji, which goes beyond the annotations. No contradictory behavior is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states exactly what the tool does and the parameter format, the second details the return structure. 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/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter getter with an output schema, the description is adequately complete. It explains the input, gives an example, and summarizes the return. No critical missing context (e.g., error cases or pagination) for expected usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has one parameter short_name with no description, so the description carries the burden. It clarifies that short_name is the sticker set identifier and provides a concrete example, effectively compensating for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb 'get' and resource 'sticker set' with the identifying parameter short_name, e.g., 'AnimatedEmojies'. It distinguishes itself from sibling tools like search_sticker_sets by specifying direct retrieval by short_name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a short_name and need the sticker set, but it does not explicitly contrast with alternatives like search_sticker_sets or get_installed_stickers. Usage context is 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains behavioral effects of each mute parameter, such as mute_until_unix semantics (None = forever, 2^31) and what show_previews, silent, and stories_muted control. This adds significant context beyond the annotations, which only indicate a mutable, non-idempotent operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one purpose sentence followed by a compact argument list. Each parameter is described in a single line with no redundant text. The structure is well-organized and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters and an output schema, and the description covers the core action plus all parameters. It omits explicit return-value details, but the output schema fills that gap. It lacks edge-case or permission information, but is adequate for a straightforward mute operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameter descriptions (0% coverage), so the description is the sole source of meaning. It provides clear explanations for all four mute-related parameters, covering defaults and edge cases. The 'chat' parameter is self-evident from its name and required status.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Замьютить уведомления чата' ('Mute chat notifications'), a specific verb+resource statement that clearly conveys the tool's function. It distinguishes from siblings like unmute_dialog and mark_read by explicitly focusing on muting notifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the purpose and the parameter descriptions, but there is no explicit guidance on when to use this tool compared to alternatives like unmute_dialog or archive_dialog. No exclusions or alternative-tool mentions are provided.
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?
The description discloses the key behavioral trait of the force parameter: when true, it unpins topics not listed. This goes beyond the annotations (which only indicate readOnlyHint=false and destructiveHint=false) by explaining a specific side effect. It does not describe other details, but the additional force behavior is valuable and consistent with annotations. No contradiction with annotations is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, starting with a one-sentence summary followed by a short Args list. Every sentence conveys necessary information without surplus. It is structured efficiently for quick comprehension, avoiding unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the primary action, the force behavior, and the key parameters. It does not explain the chat parameter, which is required, but the tool has an output schema so return values are not needed. Given the moderate complexity (3 parameters, no nested objects) and the presence of annotations, the description is mostly complete, with the chat parameter being the main omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains two of the three parameters: topic_ids_in_order (IDs in desired order) and force (unpin unlisted topics). However, it omits the required chat parameter entirely, and since schema description coverage is 0%, the description must compensate for all parameters. It partially does so by defining the two most semantically interesting parameters, but the missing chat context leaves a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: "Переставить порядок закреплённых тем" (Rearrange the order of pinned topics). It uses a specific verb (reorder) and identifies the resource (pinned forum topics), distinguishing it from sibling tools like pin_forum_topic (which pins) and get_forum_topics (which lists). 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to reorder pinned topics and includes a parameter (force) that affects whether unpinned topics are removed, providing context on alternative behaviors. However, it does not explicitly state when to prefer this over similar tools like pin_forum_topic or get_forum_topics, nor does it provide exclusions. The clear name and description make usage fairly evident, but explicit guidance on alternatives is missing.
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?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the mutation nature is known. The description adds valuable behavioral context by explaining that each bool=True means prohibition of the corresponding action, and clarifies the polarity of send_* flags – this is beyond what annotations provide. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with clear structure: purpose statement, then usage semantics, then argument explanation. Every sentence adds value, and it avoids redundant phrasing. The line breaks improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (so return values are covered) and the description covers the tool's purpose, boolean semantics, and until_unix parameter, the description is quite complete. It could mention prerequisites (e.g., admin rights) or reversibility, but these are not critical given the annotations and schema. The description is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 a general rule for all boolean parameters (bool=True means prohibition) and explains until_unix specifically. While chat and user are not described, they are self-evident. This effectively covers all 12 parameters despite not listing each one individually.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Ограничить права участника супергруппы (read-only mute и т.п.)' – restrict a supergroup participant's rights. This specific verb+resource+scope distinguishes it from siblings like ban_participant (ban) and kick_participant (remove), and the mention of 'read-only mute' clarifies the exact use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to interpret boolean flags (send_*=False allowed, True prohibited) and until_unix semantics, which is useful guidance. However, it does not explicitly say when to use this tool versus alternatives like ban_participant or kick_participant, nor does it provide exclusion criteria. The usage context is implied but not contrasted with sibling tools.
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?
Annotations indicate a write operation; description adds that drafts sync across devices and that formatting occurs at send time, going beyond structured data. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise purpose sentence followed by a brief args list; every sentence adds value with no redundancy. Well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers core behavior and key parameters; output schema exists for return values. Missing details on remaining parameters are minor, but the tool has 5 params so some context is still lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds semantics for text (empty string clears) and parse_mode (client hint), but chat, reply_to, and link_preview remain unexplained. Partially compensates for 0% schema coverage but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Сохранить серверный draft в чате' with sync detail, clearly identifying the resource and action. Distinguishes from sibling tools like clear_draft and get_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains that empty text clears the draft, which implicitly provides an alternative to clear_draft. Also clarifies parse_mode as a client hint for sending, but 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a mutating, non-idempotent operation. The description adds valuable parameter-level behavior: schedule_unix for delayed sending, comment_to requiring an enabled discussion group, and clear_draft to clear drafts. This discloses non-obvious side effects without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, starting with a one-line summary followed by a compact parameter list. Each parameter gets a brief explanation without fluff. It is longer due to the number of parameters but every line adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 9-parameter complexity and zero schema descriptions, the description covers all parameters and adds important context for non-obvious ones (e.g., comment_to prerequisites, schedule_unix format). An output schema exists, so return values are not the description's responsibility. The tool would be usable with this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description carries the entire burden. It explains each parameter (chat, text, reply_to, silent, parse_mode, link_preview, schedule_unix, comment_to, clear_draft) with sufficient context, including allowed values and special requirements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Отправить текстовое сообщение' (Send text message), a specific verb+resource combination that clearly identifies the action. It distinguishes from siblings like send_file, send_album, and send_voice by explicitly stating the text-message scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for text messages but does not explicitly state when to avoid this tool or mention alternatives like send_file or send_voice. No exclusions or comparative guidance are 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?
Annotations already signal readOnlyHint=false (mutation) and idempotentHint=false. The description adds the scenario context but does not disclose additional behavioral traits like side effects or reversibility. It is consistent with annotations and adds modest value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the action and condition efficiently. Every word earns its place, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, simple cancel operation, the description is complete: it states the action and the exact situation in which to use it. An output schema exists, so return values are covered; no further explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100% (empty schema). The description doesn't need to explain parameters, and the baseline for no-parameter tools is 4. It adds no parameter details but none are required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Отменить' (cancel) with a clear resource 'auth-flow', and adds the precise scenario 'if you requested a code but didn't enter it'. This clearly distinguishes it from siblings like auth_submit_code and auth_request_code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: when an auth-flow is unfinished, specifically after requesting a code but before entering it. It provides clear context but does not mention alternatives or exclusions, though the sibling list makes the alternative obvious.
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?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds the detail that sessions are from other devices/clients, which is more about content than behavior. It does not disclose rate limits, authentication needs, or any side effects, but the annotations cover the safety profile adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the core purpose and then a practical use case. Every word earns its place, with no unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, zero parameters, strong annotations, and presence of an output schema, the description is complete. It provides enough context about the data returned (active sessions) and the use case for auditing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline of 4 applies. The description doesn't need to explain parameters, and no parameter information is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists active account sessions across devices/clients, which is specific and distinct from the sibling terminate_authorization that terminates sessions. The noun 'Список' (list) implies the read operation, and the parenthetical clarifies the 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case: auditing who is currently logged in. It does not explicitly mention alternatives or exclusions, but the context of account session auditing is sufficient for an agent to decide when to invoke it.
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?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds that the result includes phone codes and that lang_code controls the language of names, but this is content semantics rather than behavioral side effects. No extra context like rate limits or auth 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two short sentences: the first states the purpose, and the second explains the argument. Every word earns its place, with no redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the presence of an output schema, and strong annotations, the description provides sufficient context. It states what is returned (all countries with phone codes) and the parameter's effect. No additional details like pagination or authentication are necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a string type, title, and default for lang_code with no description. The description fills the gap by explaining lang_code values ('en', 'ru', etc.) and its meaning (язык названий), which is essential for correct invocation. It compensates well for the 0% schema coverage, though the full set of codes is left open-ended.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Список всех стран с phone-кодами' (List of all countries with phone codes), which clearly identifies the tool as a list operation returning country data. This specific verb+resource combination distinguishes it from all sibling tools, which focus on messaging, chats, and account 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical '(для интерфейса добавления контактов)' specifies the intended use case—contact addition UI—providing clear context for when to invoke this tool. It does not mention exclusions or alternatives, but no alternative exists among the sibling tools.
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?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing what the config contains (DC, file limits, edit_time_limit), which goes beyond the annotations. It does not mention auth or rate limits, but for a simple getter this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise Russian sentence that front-loads the key information. No filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only config getter with an output schema, the description sufficiently conveys the purpose and content. It is complete enough 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to explain parameter usage. The baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The tool name and Russian description clearly indicate it retrieves the basic Telegram network configuration. It lists specific elements (DC, file limits, edit_time_limit), distinguishing it from sibling tools like get_app_config or get_server_version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives like get_app_config or get_server_version, but the specification of network-level config implies its purpose. No exclusions or alternative references are provided.
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?
Annotations cover readOnly=false, idempotent=false, destructive=false. The description adds behavioral context: how the signal is temporary, can be cancelled via action='cancel', and delay_seconds controls duration. This goes beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the main purpose, followed by a clean bullet-style list of arguments. No redundant or filler sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 all necessary information: what, where, and how. Minor gap: no mention of prerequisites (e.g., being a chat member) but that is not essential for this kind of tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does 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 carries the full burden. It explains chat (id or @username), action (typing, record-audio, cancel, etc.), and delay_seconds (how long to hold status), adding meaning beyond the enum and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sends an activity signal (typing/recording/sending) to a chat, using a specific verb and resource. It distinguishes itself from siblings like send_message (actual message) and set_online (online status).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implicit: the tool is for showing chat activity status. It does not explicitly mention when not to use it or name alternatives, but the purpose is clear enough for an agent to infer appropriate use.
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?
Beyond the destructiveHint annotation, the description reveals that revoke=True makes deletion irreversible and triggers an 'elicit' confirmation plus a PreToolUse hook. This is significant behavioral information that helps the agent understand side effects and safety protocols, exceeding what annotations alone 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with the main purpose in the first sentence and a focused parameter breakdown in the next. Every word adds value, and the structure front-loads the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature, the description effectively covers the core decision (revoke or not) and its consequences. The presence of an output schema reduces the need to describe return values. However, it omits details about parameter formats and potential error conditions, leaving minor gaps for a destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It explains the most important parameter, revoke, including its default and irreversibility. However, chat and message_ids are not elaborated—chat accepts integer or string, but the difference is not clarified. Thus, compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the primary function: 'Удалить сообщения' (delete messages) and immediately clarifies the default scope 'только у себя' (only for yourself). This distinguishes it from other deletion tools like delete_dialog or delete_stories, 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for each mode: default is delete only for yourself, while revoke=True deletes for everyone and triggers a confirmation flow. It effectively tells the agent when to set the revoke flag, though it does not explicitly name alternative tools or exclusion conditions.
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?
The description discloses effective behavior: it creates an invite link and explains that request_needed=true means candidates wait for approval. It also notes the title is for admin audit. Annotations already indicate this is not read-only and not destructive, and the description adds useful context about link parameters without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the core action, and uses a clean Args section. Every sentence adds value with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, has an output schema (so return format is covered), and parameters are well explained. The description lacks details about permissions or side effects, but given the annotations and low complexity, it is sufficiently complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description compensates by explaining the purpose of expire_unix, usage_limit, request_needed, and title. The only parameter not explicitly described is 'chat', but its name and role as the target chat/channel are reasonably inferable from the tool's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Создать invite-ссылку на чат/канал' (Create invite link to chat/channel), using a specific verb and resource. It is distinct from sibling tools, none of which mention creating invite links.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this tool is used to create invite links, and the parameter details clarify common usage scenarios (expiration, usage limit, approval, label). No explicit alternatives or exclusions are mentioned, but the purpose is sufficiently clear for selection.
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?
Annotations already indicate read-only/idempotent/non-destructive, so the description only needs to add scope; it does so by listing bio, common chats, premium, etc. This gives the agent a clear expectation of the returned information without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly packed lines with a clear header and an Args section. Every word adds value; no filler or repetition of schema/annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A one-parameter read-only tool with an output schema, strong annotations, and a description that specifies input semantics and result categories. No missing information is needed for correct selection/invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides only types (integer/string/null) with zero descriptions. The description compensates fully: 'user: id/@username; None = я сам' explains the accepted formats and the special null meaning, so no ambiguity remains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Расширенная инфа о пользователе (bio, общие чаты, premium, etc)'—a specific resource (user) with concrete content categories. It differentiates from sibling getters like get_me by allowing any user id/username and covering full profile details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The Args line clarifies when to pass a user vs None ('None = я сам'), which is useful operational context. However, it does not explicitly state when to prefer this over siblings like get_me or get_common_chats, nor 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and idempotent behavior. The description adds that aggressive mode iterates through index search pages, making the operation slower but more complete—a useful behavioral caveat beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and uses a bullet-like list for parameters. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema and annotations, the description covers the main parameters and includes the special aggressive-mode behavior. It omits the 'search' parameter and doesn't detail default pagination beyond the >200 hint, but remains adequate 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains the limit range, all five filter booleans, and the aggressive flag. The only gap is the 'search' parameter, which is not mentioned, so most parameters gain meaning from the text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Список участников группы/канала' (list of participants of group/channel), clearly identifying the resource and action. This is distinct from sibling tools like list_chats or get_chat_info, which deal with chats themselves rather than their members.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives practical context: valid limit range (1-200), the meaning of filters ('показать только эту категорию'), and when to use aggressive mode for channels with >200 participants. It doesn't explicitly name alternatives or exclusions, but the context is clear.
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?
The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by enumerating the allowed keys, which tells the agent which inputs are valid. It does not add safety details, but they are covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with a clear one-sentence purpose followed by a well-formatted parameter list. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with a single parameter and an output schema, the description provides the necessary information: the action, the resource, and the allowed parameter values. The output schema handles return value expectations, so the description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only specifies a string type, but the description fully enumerates all allowed values for the key parameter, which is essential for correct invocation. 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/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states that it retrieves current privacy settings for a specified key, which is a specific verb+resource combination. It clearly distinguishes from the sibling tool set_privacy by using 'get' and specifying 'privacy settings'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when one needs to read current privacy settings, but it does not explicitly mention when to use it versus set_privacy or provide exclusions. The presence of set_privacy as a sibling suggests the context, but the description itself lacks explicit 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?
Annotations indicate mutation (readOnlyHint=false) but no destructiveness. The description adds valuable behavioral detail not in annotations: that an empty emoji string removes all reactions, and how 'big' and 'add_to_recent' modify behavior. This goes beyond what annotations 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and uses a clear docstring structure for parameters. Every sentence adds value without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given 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 format need not be described. The description covers key behavioral nuances (reaction removal, big animation, recent list) and is sufficient for a low-complexity action. Minor gaps like authorization or response details are acceptable given good annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does 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 emoji parameter format and special empty-string behavior, and describes 'big' and 'add_to_recent'. However, it does not explain 'chat' or 'message_id', though their purposes are fairly inferable from names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Поставить реакцию-эмодзи на сообщение' which clearly states the action (react) and the resource (message), distinguishing it from sibling tools like send_message or edit_message. It's specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use: when you want to set an emoji reaction on a message. It doesn't explicitly mention alternatives or when not to use, but the context is clear enough given the tool name and sibling set.
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?
Annotations already indicate it is a write operation (readOnlyHint=false) and not destructive. The description adds valuable context beyond annotations: the critical distinction between 'None' (no change) and empty string (clear field), which affects invocation behavior. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences: the first states the purpose, the second explains parameter behavior. No unnecessary words, and the most operationally important information (null vs empty string) is front-loaded. Perfectly sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward profile update with three optional parameters and an output schema present, the description covers purpose and parameter semantics completely. It specifies the scope (own profile) and the behavior of all fields. No missing critical details for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries full responsibility for parameter meaning. It clearly explains that None preserves the current value while an empty string clears it, directly clarifying all three optional parameters (about, last_name, first_name). This is essential and not derivable from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates the user's own profile fields (first name, last name, bio) with a specific verb 'Изменить' (change). It distinguishes from sibling tools like update_username by listing the specific fields, and from other chat-related edits by specifying 'собственного профиля' (own profile).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (updating own profile fields) and provides parameter semantics, but it does not explicitly mention alternatives or exclusions. It lacks an explicit statement like 'for changing username, use update_username', leaving the agent to infer from the purpose.
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?
The description adds meaningful behavioral context beyond the annotations, specifically that an empty string removes the username. This clarifies a potentially destructive action, which is not covered by the readOnlyHint/destructiveHint annotations. It does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that front-loads the action and includes the key edge case. Every word adds value, with no redundancy or irrelevant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter mutation tool with an output schema and annotations, the description is complete. It covers the core action and the special removal behavior, which is sufficient 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/5
Does 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 explains the only parameter (username) by indicating that it accepts a new username and that an empty string removes it. This provides essential meaning the schema alone lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Сменить' = change) and clearly identifies the resource (the account's @username). It also adds the distinct behavior of removing the username via an empty string, which distinguishes it from broader profile tools like update_profile. This fully clarifies the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for changing or removing the account username, but it does not explicitly mention when to use it over alternatives like update_profile, nor does it state exclusions. The empty-string note is a useful behavioral hint but does not constitute guidance on tool selection.
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?
The description discloses that it 'clears previous auth-state' and returns already_authorized status, adding behavioral context beyond the annotations. While annotations already indicate non-read-only and non-idempotent behavior, this additional detail is valuable and does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary purpose, followed by a structured list of return fields. Every sentence contributes value without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with a described output schema, the description fully covers the tool's purpose, side effects, and return semantics. 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description carries no burden for parameter explanation. The baseline of 4 applies, and the description appropriately focuses on behavior and return values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'request SMS code from Telegram' and labels it 'Step 1' in the auth flow. This distinguishes it from sibling auth_submit_code, as it covers the request phase, not code submission.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context by identifying this as 'Step 1' and mentioning the already_authorized case where no code is needed. This implies when to use it, but it does not explicitly name alternatives or state when not to use it, which would warrant 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?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds value by specifying that only metadata is returned, not the password, and lists the specific metadata fields. This goes beyond the annotations and gives the agent a clear expectation of behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the main purpose, and the crucial caveat about not returning the password is clearly separated. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool, the description fully captures what it does, what it returns, and an important limitation. The output schema exists, so return details are not required, but the description still provides a human-readable summary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the description is not required to explain parameter meanings. The baseline of 4 applies, and the description effectively channels attention to the output rather than params, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the resource (configured 2FA password) and the type of information returned (enabled status, hint, recovery email). It effectively conveys 'get information about 2FA password' and is distinguishable from siblings like auth_submit_code or auth_request_code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for checking 2FA configuration status without returning the password itself. It provides a clear when-not by explicitly stating 'НЕ возвращает сам пароль' (does not return the password), but does not discuss alternatives. Since no direct alternative exists among siblings, this is adequate.
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?
Annotations mark destructiveHint=true, and the description reinforces this by describing session termination. It adds the behavioral constraint that current=true sessions are protected, which is valuable beyond annotations. It lacks details on side effects or irreversibility, but the destructive nature is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, entirely relevant, with the action and critical exception front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive tool, the description covers the action, parameter origin, and an important restriction. An output schema exists, so return-value description is unnecessary. It is sufficiently complete for agents to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description for hash_str (0% coverage), but the description explains it is the hash from get_authorizations, giving essential context. This compensates for the schema gap, though it does not elaborate on format or other constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'terminate' with the resource 'another's active session' and identifies the hash source. It explicitly distinguishes from siblings by noting that own sessions (current=true) cannot be terminated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states to use the hash from get_authorizations and that current sessions cannot be terminated, providing an explicit exclusion. However, it does not name an alternative tool for terminating one's own session, 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?
Beyond the annotations (which already indicate a non-read, non-idempotent mutation), the description adds meaningful behavioral details: the code must be a 5-digit SMS code, and if 2FA is required but password_2fa is omitted, an error will be returned asking to retry. This discloses error behavior and input prerequisites that are not in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is ultra-compact, front-loaded with 'Step 2', and lists arguments in a clear format. Every sentence adds value, and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with an output schema, the description covers the essential context: what the tool does, what each parameter means, and a key error condition. Combined with the output schema and the 'Step 2' placement, the information is sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully carries parameter meaning. It explains that 'code' is a 5-digit SMS code from Telegram and that 'password_2fa' is the cloud-2FA password, including the consequence of omitting it when 2FA is enabled. This is exactly what the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Step 2: send code (and optional 2FA password)', clearly identifying the verb (send) and resource (code). It also distinguishes itself from sibling tools like auth_request_code and auth_cancel by labeling it as step 2 in the flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Step 2' prefix gives clear sequential context, implying this should be used after requesting a code and before other authentication steps. However, it does not explicitly mention alternatives or when-not-to-use scenarios, though the context makes this largely unambiguous.
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?
Annotations already declare destructiveHint=true, but the description adds substantial context beyond that: for supergroups it performs leave+delete, for PMs it clears history with optional revoke also affecting the other party, and it discloses FloodWait retry behavior with sleeping and a maximum total wait. This is meaningful, non-obvious behavioral disclosure that goes well beyond the annotation metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise one-line summary followed by a structured Args section. Every sentence adds value, with no redundancy or fluff. It is front-loaded and easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the key complexities: batch operation, dialog-type-specific behavior, revoke semantics, and flood wait handling. It is complete enough for a destructive tool with an output schema, though it does not mention prerequisites or explicitly name sibling tools, and the undocumented ctx parameter is a minor omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the full burden and mostly succeeds. It explains chat_ids as a list of int/str dialog IDs, revoke as PM-only deletion on the other side, auto_floodwait_retry as sleeping on FloodWait, and max_total_wait_seconds as the total sleep cap. The only gap is the ctx parameter, which is present in the schema but not mentioned in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Удалить N диалогов одним MCP-вызовом' (Delete N dialogs in one MCP call), which is a specific verb+resource+scope statement. It further distinguishes between supergroups (leave + delete dialog) and PMs (clear history), clearly separating it from siblings like delete_dialog and leave_chats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear behavioral context for when to use the tool: batch deleting multiple dialogs in a single call, with special handling depending on dialog type. However, it does not explicitly name alternatives (e.g., delete_dialog for a single dialog, leave_chats to only leave), so it stops short of the explicit when/when-not guidance needed for 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?
Annotations provide readOnlyHint=false and destructiveHint=false, but the description adds valuable behavioral context by warning that the tool 'may change account state or cause flood-wait.' This goes beyond the annotations and alerts the agent to significant risks. It doesn't enumerate all possible effects but covers the key hazards.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear purpose sentence, an Args section with both parameters, and a prominent danger warning. Every sentence adds value, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a raw escape-hatch tool with broad scope and an output schema present, the description covers the essential context: what it does, how to invoke it, the main risks, and when to use it. It stops short of explaining return values or error handling, but these are less critical for a generic invoker.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It does so by describing method_path as a 'full python path' with an example, and kwargs_json as a 'JSON-string with kwargs for the method constructor.' This provides meaningful guidance beyond the bare schema, though it could be slightly more precise about the exact format requirements.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: 'call arbitrary Telegram MTProto method via Telethon.' It clearly distinguishes itself from the high-level sibling tools by positioning itself as a low-level raw invocation tool. The warning 'use only when the needed high-level method is missing' further clarifies its role as a fallback.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Use only when the needed high-level method is missing.' This directly tells the agent when to use this tool and implies that high-level alternatives should be preferred. The danger warning also sets expectations for cautious usage.
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?
Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral depth by explaining that 'limit' is an upper bound on the raw fetch before filtering, and 'compact' reduces payload size by ~5x. This goes beyond the annotation flags and gives the agent useful implementation details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured using a bulleted list. The first line immediately states the core purpose and exclusion. Each parameter gets a brief, clearly formatted explanation. No superfluous words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 7 optional parameters and the existence of an output schema, the description covers all necessary aspects: what type of items are returned, how filtering works, and performance-related options. It fully compensates for the lack of schema descriptions and leaves no major gaps in understanding the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description carries the full burden. It thoroughly explains every parameter: archived enum semantics, limit as a raw-fetch bound, only_unread filtering, is_pinned options, min/max participants as subscriber filters, and compact payload behavior. This adds meaningful context that the schema alone lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as listing broadcast channels only, explicitly excluding supergroups. This distinguishes it from sibling tools like list_chats, list_groups, and list_pm_users. The verb 'list' and resource 'channels' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states that this tool handles only broadcast channels (no supergroups), which gives clear context for when to use it over alternatives. It does not explicitly name alternative tools or state exclusions, but the scoping is implied strongly. The parameter descriptions also clarify how to control the results, e.g., archived, only_unread, and participant count filters.
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?
The annotations already mark the operation as read-only, open-world, idempotent, and non-destructive. The description adds context by stating it invokes the client's LLM and, if sampling is unsupported, returns raw messages and asks the user to summarize. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of a one-line summary, a short structured Args block, and a conditional note about unsupported sampling. Each element is necessary and compact, with the main purpose front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and safe-read annotations, the description provides enough operational detail: purpose, parameter semantics, and fallback behavior. It covers the tool's core functionality without unnecessary elaboration, making it complete for an agent to select and invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 0% of parameters, so the description's 'Args' section is essential. It explains chat as 'id или @username,' limit as '1-200 сообщений,' and instruction with concrete examples like 'сделай маркированный список' and 'выдели action items,' adding meaning beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Резюме последних N сообщений чата через LLM-вызов клиента,' which clearly identifies the function as summarizing the last N chat messages using an LLM call. This is a specific verb+resource+scope that distinguishes it from sibling tools like get_history or search_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for any need to get a concise summary of recent conversation, and the fallback note ('Если клиент не поддерживает sampling — возвращает сырые сообщения') sets expectations when the client lacks sampling support. However, it doesn't explicitly name alternative tools or exclusion conditions, so it's a clear context without full guidance.
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?
Beyond the readOnly/idempotent annotations, the description discloses that force_reconnect resets the singleton client and reconnects, and that the tool always returns a full HealthReport even on errors, including diagnostic fields (session_path, session_exists, data_dir). This adds significant behavioral context not present in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence purpose, a clear Args section for the parameter, and a Returns section. Every sentence earns its place, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter health-check tool with an output schema (HealthReport) already defined, the description covers the core purpose, the parameter's side effect, and the special guarantee of returning full data even on errors. This is complete 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/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema for force_reconnect contains only a name, type, and default, with no description (0% schema description coverage). The tool description fully compensates by explaining that True resets the singleton client and reconnects, and when this is useful, adding rich meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as a health check for Telegram connectivity and session validity ('Проверка работоспособности: соединение с Telegram, валидность сессии'). It uses a specific verb and resource, and the focus on diagnostics distinguishes it from sibling operational 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete usage scenario: using force_reconnect after 'claudegram-auth' when the server may have cached a stale no-auth state. It implies general use for diagnosing connection issues, but does not explicitly mention alternatives or exclusion cases, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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:

[![claudegram MCP server](https://glama.ai/mcp/servers/sanjar-x/claudegram/badges/card.svg)](https://glama.ai/mcp/servers/sanjar-x/claudegram)

Score Badge

Copy to your README.md:

[![claudegram MCP server](https://glama.ai/mcp/servers/sanjar-x/claudegram/badges/score.svg)](https://glama.ai/mcp/servers/sanjar-x/claudegram)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/sanjar-x/claudegram'

If you have feedback or need assistance with the MCP directory API, please join our Discord server