telegram-api-mcp

Server Quality Checklist

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

Latest release: v0.1.0
Disambiguation5/5
Each tool corresponds to a distinct Telegram Bot API method with clearly different purposes. Even similar operations like edit_message_text vs edit_message_caption or ban_chat_member vs ban_chat_sender_chat have precise descriptions that eliminate ambiguity.
Naming Consistency4/5
The vast majority of tools follow a consistent verb_noun snake_case pattern (e.g., send_message, get_chat, delete_sticker). A few generic commands like 'close', 'log_out', and 'get_me' deviate slightly, but the overall pattern is highly predictable.
Tool Count4/5
173 tools is large, but the server is a comprehensive wrapper for the entire Telegram Bot API, which justifies the count. Each tool represents a distinct API method and earns its place, though the sheer number may be overwhelming for some agents.
Completeness5/5
The tool surface covers all major areas of the Telegram Bot API: messaging, media, chat management, stickers, payments, business accounts, stories, gifts, inline mode, webhooks, and more. No obvious gaps or dead ends are apparent.
Average 3.3/5 across 162 of 173 tools scored. Lowest: 1.3/5.
See the Tool Scores section below for per-tool breakdowns.
- 0 of 1 community issues answered or closed in the last 6 months
- 13 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
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

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is a non-read-only, non-idempotent, and non-destructive operation, but the description adds no behavioral context beyond that. It does not disclose side effects, the need for scoring updates, or any other operational traits.
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 concise at three words, but this is under-specification, not effective conciseness. It offers no structural benefit and merely mirrors the tool name, which would leave an agent without actionable information.
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?
For a tool with 10 parameters and no output schema, this description is drastically incomplete. It provides no context about how to construct the request, what the game short name refers to, or any expected behavior, making it nearly impossible 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.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 20% schema description coverage, the description needed to compensate by clarifying key parameters, but it provides none. It does not mention chat_id or game_short_name, which are required, nor any of the optional parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Send a game' essentially restates the tool name 'send_game' with no additional information. It identifies the action and resource but fails to explain what a game is or how it differs from other send operations, falling into tautology.
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. It does not mention any prerequisites, such as registering the game, nor does it note that send_game typically only works in private chats.
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, so the safety profile is clear. However, the description adds no behavioral context such as return format, potential errors, or authentication requirements, leaving the agent without crucial operational information.
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, efficient sentence with no redundancy. However, it is under-specified to the point of being nearly a tautology, so it is not as valuable as a concise, information-dense description.
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 (one parameter) but the description does not mention that this is a read operation returning a BusinessConnection object, nor does it explain what a business connection is. With no output schema and minimal context, the description is incomplete for an agent to understand the full behavior.
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 business_connection_id parameter, its format, or how to obtain it. The description adds no meaning beyond the raw schema, failing 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.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get information about a business connection' essentially restates the tool name without adding specificity. It does not distinguish this tool from sibling 'get' tools like get_business_account_gifts or get_chat, and the concept of 'business connection' remains undefined.
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, what prerequisites exist, or how it relates to alternative tools. There is no mention of its role within the broader Telegram Bot API business connection workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations indicating readOnlyHint false and destructiveHint false, the tool is clearly a write operation. However, the description adds no behavioral context such as side effects, required permissions, or message delivery behavior. It fails to mention that this sends a visual venue card to a chat, which is 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is quite short and free of fluff, which is concise. However, it is under-specified to the point of being unhelpful for a tool with 17 parameters. It is a complete sentence but lacks structural detail or front-loaded key information, so it does not earn its place effectively.
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?
Given the tool's complexity (17 parameters, no output schema, low schema description coverage), this one-liner is severely incomplete. It provides no information about return values, side effects, or operational context. An agent would be unable to correctly invoke or understand the tool's behavior from this description alone.
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 only 18%, so the description must compensate for undocumented parameters. It does not explain any of the 17 parameters, including required fields like chat_id, latitude, longitude, title, and address. Since the schema itself is sparse, the description offers zero semantic help with parameter meaning.
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 states a clear verb ('Send') and resource ('information about a venue'), but it is vague about what sending a venue actually entails. It does not distinguish from sibling tools like send_location, and could be interpreted as sending a text description rather than a geopinned venue message. Tautology is avoided, but specificity is lacking.
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 vs alternatives like send_location or send_message. It does not mention exclusions, prerequisites, or typical use cases, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, so the description does not need to restate that. However, it adds no behavioral context beyond that, such as message delivery semantics, error conditions, or side effects. With minimal annotation detail and no additional description, the tool's behavior is largely undisclosed.
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, which is concise, but it is essentially a tautology of the tool name. It provides no structured information, no examples, and no breakdown of key behaviors. The sentence is under-specified rather than efficiently informative.
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 11 parameters, no output schema, and low schema coverage, the description is completely inadequate. There is no mention of return values, possible failures, permission requirements, or any contextual cues that would help an agent invoke this 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 only 36%, with just chat_id and sticker having descriptions. The description 'Send a sticker' provides no information about any of the 11 parameters, leaving all undocumented parameters without any clue to their purpose. 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Send' and the resource 'sticker', which distinguishes it from sibling tools like send_message, send_photo, and send_animation. However, it lacks any additional scope or context, so it falls short of a top-tier description that would include specifics such as target chat or method of sticker identification.
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. No mention of when stickers are appropriate, prerequisites, or exclusions. The sibling list contains many send_* tools, and the description does not clarify when this tool should be selected over them.
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 this is a non-read-only, non-destructive operation, but the description adds no further behavioral context. It does not disclose what happens to original messages, whether captions are preserved, or any permission requirements, which are important 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. However, for a tool with 7 parameters, it is under-specified rather than appropriately concise.
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 no output schema and only a minimal description, the agent lacks essential context about return values, parameter semantics, and how this tool differs from similar sibling tools like copy_message or forward_messages. The description is far from 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.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 14%, yet the description provides no parameter information. Required parameters like message_ids and from_chat_id are left entirely unexplained, and the description does not compensate for the schema's sparse 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 a specific action ('Copy') and resource ('multiple messages'), and the 'at once' phrasing signals batch behavior. It is distinguishable from the sibling copy_message tool by emphasizing plurality, though it does not explicitly mention source/destination 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?
There is no guidance on when to use copy_messages versus the singular copy_message or forward_messages. No conditions, prerequisites, or exclusions are provided, leaving the agent to infer the appropriate 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 this is a non-read-only, non-idempotent, non-destructive operation. The description adds no extra behavior context (e.g., that existing invite links remain valid, or that each call creates a fresh link). No contradiction exists, but the description fails to add value beyond the structured hints.
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, front-loaded with the verb, but it is under-specified rather than efficiently informative. It lacks essential context, so it is not a model of concise clarity—brevity at the expense of meaning.
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 five parameters, no output schema, and a rich set of related invite-link tools, this description is far too sparse. It does not clarify what the return value represents (the invite link object), how parameters interact, or the tool's relationship to other invite link functions, leaving significant gaps in an agent's understanding.
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 only 20%, with four parameters (name, expire_date, member_limit, creates_join_request) completely undocumented. The description does not explain any parameter meaning or how they affect the invite link, making it difficult for an agent to choose correct values.
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 verb 'Create' and resource 'additional invite link' clearly state the action. The word 'additional' distinguishes this from export_chat_invite_link (primary link) and create_chat_subscription_invite_link (subscription-based). However, it doesn't explicitly mention the chat context, relying on the tool name and sibling list for full clarity.
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 export_chat_invite_link, edit_chat_invite_link, or revoke_chat_invite_link. Prerequisites such as bot admin rights or chat permissions are not mentioned, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read-only, non-idempotent operation, but the description adds no additional behavioral context. It does not mention side effects, required permissions, or the need for payment credentials, so the agent relies solely on 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 sentence with no redundancy, earning high marks for conciseness. However, it is so brief that it borders on under-specification, though it still has a clear structure.
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?
Given the 7-parameter schema, no output schema, and sparse annotations, the description is severely incomplete. It does not explain return format, required parameter semantics, or any behavioral caveats, making it inadequate for correct invocation.
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?
With 0% schema description coverage and no parameter details in the description, the agent gets no help understanding what 'title', 'payload', 'currency', or other fields mean. The description only says 'invoice' without mapping to any of the 7 parameters.
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 'Create a link for an invoice' clearly identifies the action (create) and the resource (invoice link), distinguishing it from sending an invoice via send_invoice by focusing on link creation. However, it does not explicitly contrast with sibling tools like create_chat_invite_link, so it falls just short of full 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 guidance is provided on when to use this tool versus alternatives such as send_invoice or create_chat_invite_link. The description only states what it does, not when to prefer it over siblings or any prerequisites like requiring a provider token.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'remove' which implies a destructive action, but the annotation destructiveHint=false. This is a direct contradiction; removing a profile photo is inherently destructive (replaces/removes existing data). No other behavioral context is provided beyond the annotation, and the description adds no clarity about permissions, reversibility, or effects.
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, direct sentence with no filler. It is appropriately front-loaded with the action, but it is so brief that it misses opportunities to add value. Still, for what it includes, it is concise and well-structured.
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 description lacks critical context: no explanation of return values (no output schema), no mention of photo_id optionality, no guidance on prerequisites, and no clarity on the distinction between business and personal profile photos. With minimal annotations and no parameter descriptions, the agent is left with significant 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 input schema lists business_connection_id (required) and photo_id (optional), but the description does not explain their purpose or semantics. With 0% schema description coverage, the agent has no information about what these parameters mean, how to obtain them, or how they influence the removal operation.
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 (remove) and resource (business account profile photo), making it easy to distinguish from related tools like remove_my_profile_photo or set_business_account_profile_photo. It could be more explicit about the business-account scope vs. personal, but the verb+resource is specific enough.
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 such as remove_my_profile_photo (for personal accounts) or set_business_account_profile_photo (for setting/updating). The description does not mention any prerequisites or context, 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 this is a non-read-only, idempotent, non-destructive operation. The description adds no additional behavioral context, such as the effect on a game message, required user participation, or error conditions, so it offers no value 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no wasted words, but it is under-specified for a tool with 7 parameters and no schema descriptions. It is concise but not appropriately sized, meriting a middle 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?
With no output schema and a complex set of parameters, the description should provide more context about when and how to use this tool. It only states the basic purpose, omitting parameter semantics, alternative guidance, and behavioral details, making it incomplete for real-world invocation.
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 0% description coverage, and the description does not explain any of the 7 parameters (e.g., force, chat_id, message_id). The description only implies user and score, leaving the majority of parameters completely unspecified, so it fails to compensate for the schema gap.
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 action (set score) and the resource (a user in a game), distinguishing it from related tools like get_game_high_scores. It lacks explicit mention of message/chat context or differentiation from alternative scores, so it doesn't reach 5.
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 send_game or get_game_high_scores. There are no examples, prerequisites, 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.
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. Annotations indicate this is a non-read-only, non-idempotent, non-destructive operation. The description repeats the send action but does not disclose additional traits such as permissions, rate limits, 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks essential context. It contains a version number 'v9.1' that may be confusing and doesn't add functional clarity. It could be considered under-specified rather than efficiently concise.
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 10 parameters, no output schema, and minimal schema descriptions. The description only says 'send an interactive checklist', which is insufficient for an agent to correctly invoke the tool without further knowledge. It does not explain the structure of the checklist, the role of effect_id, or how reply_markup interacts with the checklist.
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 only 30% schema description coverage and 10 parameters, the description's mention of 'interactive checklist' suggests the checklist parameter is the core payload, but it provides no details on structuring the checklist or the meaning of other parameters. This is minimal compensation for the sparse 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 uses a specific verb 'Send' and resource 'interactive checklist', clearly indicating the tool's function. It distinguishes from sibling tools like edit_message_checklist by specifying the send action. However, it doesn't elaborate on what an interactive checklist is, but the purpose 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 is provided on when to use this tool versus alternatives. The description only states the action without mentioning any prerequisites, exclusions, or alternatives, 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?
Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses no additional behavioral traits. It does not mention side effects, requirements, or response characteristics, so the agent gains little extra insight.
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 extremely concise with one short sentence, which is good for readability, but it under-specifies the tool. It earns a moderate score because conciseness is positive, yet the content is insufficient for the tool's complexity.
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?
Given the tool has 13 parameters, no output schema, and minimal annotations, the one-sentence description is grossly inadequate. It does not explain required inputs, optional behaviors, or any preconditions, making it nearly impossible for an agent to use the tool correctly without additional inference.
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 only 23% (three of thirteen parameters have descriptions), and the description provides no parameter details. It does not compensate for the low coverage, leaving semantics of phone_number, first_name, etc. to be inferred from names 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 'Send a phone contact' clearly uses a specific verb and resource, indicating it sends a contact card. It distinguishes from sibling send tools by naming the resource type, though it does not elaborate on the 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?
No guidance is provided on when to use this tool versus alternatives such as send_message or other send methods. The description lacks any contextual direction 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 indicate a non-read-only, non-destructive, non-idempotent operation, and the description's 'create' is consistent. However, it adds no behavioral context beyond the annotations—no failure conditions, ownership requirements, or side effects are 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 concise sentence with no redundant words. It is front-loaded and easy to scan, though it under-specifies—this is more a completeness concern than a conciseness one.
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 six parameters (three required) and no output schema, but the description provides none of the needed context. It doesn't mention return values or the meaning of key parameters like stickers and sticker_type, making it inadequate for reliable invocation.
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 of the six parameters. It only loosely implies user ownership via 'owned by a user', but name, title, stickers, sticker_type, and needs_repainting remain entirely undefined.
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 a create operation for a new sticker set owned by a user, which matches the tool name. However, it does not explicitly distinguish this from related sibling tools like add_sticker_to_set or set_sticker_set_title, relying on the verb 'create' to imply distinction.
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 alternative sticker-set operations such as upload_sticker_file, add_sticker_to_set, or set_sticker_set_title. The description gives only a generic action without any context about 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?
Annotations indicate a mutating, idempotent, and non-destructive operation, but the description adds no behavioral context beyond that. It fails to disclose what editing a checklist entails, side effects, or whether the checklist parameter replaces the entire message.
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, but it is under-specified. The version suffix '(v9.1)' adds no value and could be considered noise, while the core sentence is too terse to be genuinely helpful.
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 four parameters, no output schema, and the concept of a 'checklist' that is likely specific to this API, the description omits critical details such as how the checklist is updated, whether partial edits are supported, and what the response contains.
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 only 25% (only chat_id is described). The description does not explain the 'checklist' or 'reply_markup' parameters, nor does it clarify which parameters are needed for editing. It adds no meaning beyond the tool name.
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?
Purpose is clear: 'Edit a checklist message' uses a specific verb and resource type, distinguishing it from generic edit_message_text or edit_message_caption. However, the version suffix '(v9.1)' is unnecessary and slightly undermines clarity.
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 edit_message_text or send_checklist. No prerequisites, exclusions, or context 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 discloses only the basic action, with no additional behavioral context beyond what annotations already convey (mutation, idempotent, not destructive). It does not mention constraints like the need for a live location message, how coordinates are updated, or any side effects. No contradiction with annotations, but no added value.
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 at five words, with no wasted text or redundant phrasing. It is front-loaded with the action. However, its brevity sacrifices useful detail, so it does not achieve a perfect score for helpfulness.
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?
For a mutation tool with 9 parameters, low schema coverage, and no output schema, this description is severely inadequate. It does not explain return values, prerequisites, identification requirements (chat_id/message_id vs inline_message_id), or parameter constraints, making it nearly useless 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.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, so the description carries a heavy burden for explaining parameters. It mentions nothing about latitude, longitude, chat_id, message_id, or other fields, failing to compensate for the schema's sparse descriptions. The action of editing a live location implies coordinates and message identification, but this is not explicitly stated.
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 'Edit a live location message' clearly uses a specific verb ('Edit') and resource ('live location message'), making the primary purpose clear. It is distinguished from most siblings by the explicit object, though it does not differentiate from related edit tools like edit_message_text or stop_message_live_location.
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?
Provides no guidance on when to use this tool versus alternatives such as stop_message_live_location or other edit_message_* tools. No prerequisites, exclusions, or context signals are given beyond the basic action.
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 the annotations already provide. Annotations indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it is a safe read operation. However, the description does not disclose any additional behavior, such as how scores are scoped to a user or message.
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. 'Get high scores for a game.' is front-loaded and easy to parse. However, it is slightly under-specified, though this is more of a completeness issue than a conciseness issue.
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 the tool has four parameters and no output schema, the description is too minimal to guide correct invocation. It does not mention the need for user_id, the role of chat_id/message_id/inline_message_id, or what the response contains. The context of the tool within the game API (e.g., as a companion to send_game and set_game_score) is not explained.
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 0% description coverage, and the description does not explain any of the four parameters (user_id, chat_id, message_id, inline_message_id). The parameter names are somewhat self-evident, but the description must compensate for the lack of schema descriptions, which it fails to do. No information about which parameters are required or how they interplay is provided.
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 action clearly: 'Get high scores for a game.' It specifies a verb and resource, making the tool's purpose understandable. However, it does not differentiate it from sibling tools like set_game_score or get_user_profile_photos, though the name itself is fairly specific.
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. The description does not mention any prerequisites, such as the need for a user_id or the context of message_id vs inline_message_id. 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.
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 further behavioral details such as side effects, payment flow implications, or requirements. It merely restates the core action without disclosing any additional traits that would help the agent anticipate outcomes or prerequisites.
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 essential action and purpose. It avoids unnecessary words and is not tautological, making it efficient and easy to parse.
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?
Given the tool complexity (29 parameters, no output schema, and poor schema descriptions), a one-line description is grossly incomplete. It fails to explain return values, required setup (e.g., provider token), edge cases, or any additional context needed to use the tool safely and effectively.
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?
With schema description coverage at only 10%, the description carries the burden to explain key parameters, but it mentions none. The description does not clarify what fields like 'prices', 'currency', 'payload', or 'provider_token' mean or how they relate to sending an invoice. This leaves the agent with almost no semantic understanding of the 29 parameters.
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 'Send an invoice for payment' clearly states the action (send) and the resource (invoice), and 'for payment' adds context about the purpose. It is specific enough to differentiate from tools like 'create_invoice_link' at a basic level, though it does not explicitly mention that it sends to a chat or how it differs from similar payment-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 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 'create_invoice_link' or 'send_message'. There are no usage examples, prerequisites, or exclusions, leaving the agent without context for selecting this tool appropriately.
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 write operation (readOnlyHint=false) and not idempotent. The description adds no additional behavioral context such as permission requirements, live location behavior, or whether the message can be edited later. It merely restates 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short and front-loaded, but it is under-specified for a tool with many parameters. It lacks qualifying details that would make the single sentence more useful, though it has no wasted words.
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 high parameter count, low schema coverage, and lack of output schema, the description is too brief to place the tool in context. It doesn't mention that this is a Telegram message send operation, nor does it explain the significance of live location 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?
The input schema has 15 parameters but only ~20% have descriptions. The description does not explain any of the optional parameters (e.g., live_period, heading, proximity_alert_radius) and 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Send a point on the map' clearly identifies a send action and the resource (a map point), which distinguishes it from sibling send_* tools like send_photo or send_venue. However, it doesn't explicitly mention sending to a chat or live location capabilities, so it's not fully specific.
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 such as send_venue (which includes an address) or edit_message_live_location for updating live locations. There are no prerequisites, exclusions, or contextual hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what the annotations already imply. While annotations indicate it's a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false), the description does not mention side effects like the topic being hidden or the need for admin permissions, nor whether it can be undone by reopening.
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 that is immediately front-loaded. It avoids unnecessary words, but it is so brief that it nearly restates the tool name. Still, it's appropriately sized for a simple action, though it sacrifices completeness 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?
Given the simple schema (one parameter) and annotations, the description is not complete enough. It lacks context about when to use this tool (e.g., in a supergroup with the General topic), what closing entails (e.g., it hides the topic for users), and how it relates to sibling tools like reopen_general_forum_topic. This is a minimal description that leaves an agent guessing.
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 covers the one parameter (chat_id) with a description 'Chat ID or @username', so schema coverage is 100%. The tool description adds no additional meaning about the parameter, but the baseline of 3 is appropriate because the schema is self-sufficient.
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 'Close the 'General' topic.' clearly identifies the action (close) and the resource (the General topic). It distinguishes from siblings like close_forum_topic by specifying 'General'. However, it's terse and doesn't mention that this applies to a specific chat, relying on the parameter for that 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?
There is no guidance on when to use this tool versus alternatives such as close_forum_topic or reopen_general_forum_topic. The description doesn't mention prerequisites, such as the chat being a supergroup or needing admin rights, nor does it say it's for closing the default topic only.
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), non-destructive (destructiveHint=false), and idempotent (idempotentHint=true). The description adds no behavioral context beyond the verb 'edit'—no mention of side effects, field replacement semantics, permissions, or response 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 sentence, which is concise and front-loaded. However, the inclusion of '(v9.0)' is unnecessary clutter that adds no functional value, slightly reducing structural efficiency.
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?
For a tool with 7 parameters, no output schema, and minimal annotations, a one-sentence description is drastically insufficient. It fails to explain story editing semantics, constraints, or expected outcomes, making it nearly impossible 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.
Parameters1/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 required to compensate for the lack of parameter documentation, but it mentions none of the 7 parameters (e.g., caption, areas, parse_mode). The agent receives no explanation of what these fields mean or how to use them.
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 'Edit' and the resource 'posted story', making the tool's function immediately obvious. This also distinguishes it from sibling tools like 'post_story' or 'delete_story', which handle creation and removal respectively.
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 such as 'post_story' or the 'edit_message_*' family. It lacks any mention of prerequisites, exclusions, or contextual cues, leaving the agent to infer usage solely from the tool 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 this is a non-read-only, non-destructive operation, but the description adds no extra behavioral context. It does not disclose whether forwarding preserves original authorship, requires special permissions, or has any side effects beyond the forward itself.
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 sentence with no filler, front-loading the action and object. It is appropriately concise for a simple operation, though it could be slightly more informative 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?
There is no output schema, so the description should explain return values, error behavior, or limitations, but it does not. With six parameters and many sibling tools, the description is too minimal to fully support correct selection and 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 very low (17%), with only chat_id being described. The description mentions 'from one chat to another' but does not explain the meaning or usage of message_id, protect_content, disable_notification, or message_thread_id, failing to compensate for the sparse 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 ('forward') and the resource ('a message'), including origin and destination ('from one chat to another'). It is specific enough to distinguish from many sibling tools, though it does not explicitly differentiate from 'forward_messages' or 'copy_message'.
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 forward_messages, copy_message, or send_message. There is no mention of prerequisites, limitations, or typical use cases, leaving the agent to infer usage from the tool 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 provide. It does not mention requirements (e.g., admin rights), side effects (e.g., replacing an existing pin), or the effect of disable_notification. Annotations declare it is a mutation and idempotent, but the description contributes no extra disclosure.
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 with no filler, but it is essentially a rephrasing of the tool name and provides no additional structure or context. It is not overly verbose, but it is under-specified for the tool's complexity.
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 four parameters and no output schema, the description is incomplete. It lacks usage context, side effects, parameter clarifications, and any mention of related operations. The agent would need additional information to use the tool correctly beyond the basic 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 only 25% (chat_id has a description). The tool description 'Pin a message in a chat' adds no meaning for message_id, disable_notification, or business_connection_id. With low schema coverage, the description needs to compensate but 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 tool pins a message in a chat, using a specific verb ('pin') and resource ('message in a chat'). It distinguishes from sibling unpin tools (e.g., unpin_chat_message), so there is no ambiguity about its 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 unpin_chat_message or other chat modification tools. There is no mention of exclusions, prerequisites, or context that would help an agent choose this tool over others.
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 verb 'Repost'. Annotations already declare the tool is not read-only, not idempotent, and not destructive, but the description does not disclose side effects, permission requirements, or what happens to the original story. It simply restates the action without enriching the agent's understanding of the tool's 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler words, making it appropriately front-loaded with the action verb and resource. The version suffix '(v9.3)' is minor and not detrimental. It earns a high score for efficiency, though it could add more detail without losing 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 3 required parameters and no output schema, the one-line description is insufficient. It doesn't explain how to obtain story_sender_chat_id or story_id, whether the bot requires special permissions in the destination chat, or whether the repost is a copy or a reference. The annotations help somewhat, but the description alone does not provide enough context for reliable invocation across 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?
The input schema only describes chat_id ('Chat ID or @username'), leaving story_id and story_sender_chat_id undocumented. With schema coverage at 33%, the description must compensate but only vaguely implies the roles ('to another chat' hints at chat_id). It fails to clarify how story_sender_chat_id and story_id relate to the source story, leaving the agent to infer from parameter names 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 the action with a specific verb ('Repost'), resource ('a story'), and target ('another chat'), making the tool's purpose immediately understandable. It implicitly distinguishes from siblings like post_story by referencing an existing story, but it does not explicitly call out alternatives like forward_message or copy_message, so it falls short of a perfect purpose score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/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 forward_message, copy_message, or post_story. It mentions no prerequisites, restrictions, or scenarios where reposting is the preferred choice, leaving the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only, non-destructive, and non-idempotent behavior. The description adds minimal behavioral context beyond the animated/random nature, which is part of the core purpose. It does not disclose side effects, required permissions, or return value characteristics.
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, front-loaded sentence with no unnecessary words. It is efficient and easy to parse. However, it is under-specified for the tool's complexity, but this is more a completeness issue than a conciseness one.
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?
For a tool with 10 parameters, no output schema, and many sibling send_* tools, this description is inadequate. It does not mention return values, parameter roles, or usage scenarios. The agent cannot determine how to invoke the tool correctly without external knowledge.
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 only 30%, and the description does not compensate. It provides no explanations for the 10 parameters, including non-obvious ones like effect_id, protect_content, business_connection_id, or the odd allow_paid_broadcast/disable_notification references. The description adds no parameter semantics beyond what the schema already offers.
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 (an animated emoji displaying a random value). It distinguishes this tool from other send_* tools like send_sticker or send_photo by emphasizing the random-value aspect, which maps directly to the dice functionality.
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 mention when to use this tool versus alternatives, nor does it provide any context or exclusions. The agent must infer usage solely from the tool name and 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 a non-read-only, non-destructive operation. The description adds no additional behavioral context, such as delivery semantics, required permissions, format limitations, or side effects 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 a single concise sentence with no wasted words. However, it is so terse that it sacrifices valuable explanatory content, making it minimally acceptable.
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 15 parameters and no output schema, this description is severely under-specified. It lacks essential context such as file size limits, return behavior, error conditions, or how the document is sent, leaving the agent without enough information to use the tool confidently.
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 only 53%, so the description should compensate by explaining key parameter behavior. It does not mention any parameters or their meanings, leaving the agent to rely solely on the sparse 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 the action ('Send') and the resource ('a general file (document)'). However, it does not explicitly differentiate from sibling tools like send_photo or send_video, relying on the word 'general' to imply the distinction.
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 vs alternatives. The word 'general' hints at use for non-specific file types, but there are no explicit exclusions, prerequisites, or alternative tool references.
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. The annotations already indicate the operation is non-read-only, idempotent, and non-destructive. The description simply restates the action, so it provides 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 of ten words, with no redundant information. It is appropriately front-loaded and easy to parse.
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 three parameters and no output schema, the description is too sparse. It doesn't explain what a business connection is, how to obtain the connection ID, or whether setting the name updates existing values. The tool is simple but the description leaves the agent without enough context to invoke it confidently.
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?
With 0% schema description coverage and no parameter explanations in the description, the agent cannot infer the meaning of business_connection_id, first_name, or last_name. The description only vaguely references 'name' without mapping it to the schema fields.
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') and the resource ('name of a connected business account'), distinguishing it from sibling tools like set_business_account_username or set_business_account_bio. However, it doesn't specify that the name consists of first and last name, which the schema reveals.
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 doesn't mention prerequisites (e.g., having a business connection) or situations where this should be used instead of set_my_name or other business account settings.
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 disclose readOnly=false, idempotent=true, destructive=false. The description adds no additional behavioral context such as whether the name overwrites an existing one, whether language_code is required, or any 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence. However, it is so minimal that it fails to convey necessary information, making it under-specified rather than appropriately concise.
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 two-parameter tool with no output schema, the description is too sparse. It omits critical context about the 'language_code' parameter and any behavioral details, leaving the agent unprepared to invoke it 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 has 0% description coverage, and the description does not explain the meaning or constraints of 'name' or 'language_code'. The description merely repeats the parameter name without adding any 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 clearly states the action and target: 'Set the bot's name.' This is specific and distinguishes it from sibling tools like set_my_description, set_my_commands, or set_business_account_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, nor any context about prerequisites or conditions. Users are left 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.
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 agent knows this is a write operation. However, the description adds no behavioral context beyond the version tag '(v9.4)', which does not explain effects, errors, or required permissions. It relies entirely on 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 sentence and not padded, but it omits essential parameter guidance and includes a vague version note '(v9.4)'. It is concise but under-informative, missing key information needed for correct invocation.
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 only one parameter and no output schema, the description should at least explain what 'photo' accepts. It does not. The annotations cover safety profile, but the description is incomplete for a usable tool, leaving the agent to guess the parameter format.
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 input schema has one property 'photo' with an empty schema, providing zero type or format details. The description does not mention the parameter at all, so there is no explanation of what value to pass (e.g., file ID, URL). With 0% schema coverage, the description fails to compensate.
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 'Set the bot's profile photo' with a specific verb and resource, clearly indicating it changes the bot's own profile photo. This distinguishes it from siblings like set_chat_photo (for chats) and set_business_account_profile_photo (for business accounts).
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 exclusions, prerequisites, or refer to sibling tools. The phrase 'bot's profile photo' implies a specific scope, but there is no explicit usage instruction.
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 idempotency and non-destructive behavior, but the description adds no extra context such as side effects, endpoint requirements, or error conditions. It describes only the essential action without behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is a single front-loaded sentence with no repetition or filler. It is short but loses the opportunity to convey essential context; however, for what it states, it is concise.
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 a complex schema, numerous sibling tools, and no output schema, this one-line description is grossly insufficient. It fails to mention return values, error scenarios, or the implications of setting a webhook (e.g., replacing existing configuration).
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 defines 7 parameters with no descriptions, and the tool description does not elaborate on any of them. Even the 'url' parameter is not explained beyond being a URL, leaving room for ambiguity around format or security 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 uses a specific verb 'Set' and identifies the resource 'webhook URL', clearly distinguishing it from webhook querying (get_webhook_info) and removal (delete_webhook). It conveys the core action unambiguously.
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 get_webhook_info or delete_webhook. The description lacks any mention of configuration workflows 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?
Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds no behavioral context beyond the literal action; it fails to mention prerequisites like the user owning the set or that the sticker must be uploaded via upload_sticker_file, nor any side effects on the set.
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 efficient sentence with no fluff, but it is under-specified for a tool with three undocumented parameters. Conciseness is achieved at the expense of utility, so it earns a moderate score rather than a higher one.
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 three parameters lacking any description, no output schema, and only a one-sentence purpose statement, the description is grossly inadequate for an AI agent to invoke the tool correctly. It omits crucial details like the role of user_id, the format of sticker, and prerequisites such as uploading the sticker first.
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%, so the description must compensate, but it does not explain any of the three parameters. It mentions 'set' and 'sticker' but does not clarify that user_id identifies the set owner, what 'name' refers to (the set name), or how 'sticker' should be provided (e.g., already uploaded file).
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 'Add' with the resource 'sticker to an existing set,' clearly indicating the action and scope. This distinguishes it from siblings like create_new_sticker_set, which creates a new set, and delete_sticker_from_set, which removes a sticker.
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 'existing set' implies this tool is not for creating a new set, providing some usage context. However, there is no explicit mention of alternatives or when not to use this tool, such as requiring the set to already exist or the sticker to be uploaded first, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds little beyond the annotations. It does not disclose what happens when 'ok' is true or false, whether shipping_options must be provided, or any side effects. Since readOnlyHint=false, the agent knows it's a write operation, but the description fails to elaborate on the consequences of the reply.
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 concise and front-loaded, but it is under-specified. The second clause about is_flexible adds useful context but is not essential to the core purpose. It is not overly verbose, yet the brevity sacrifices critical information.
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 4 parameters, 0% schema coverage, and no output schema, the description needs to provide substantial guidance. It offers almost none, leaving the agent without a clear understanding of how to construct a valid reply or interpret the parameters. This is completely inadequate for a tool of this complexity.
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 says nothing about the parameters. The agent must infer that 'shipping_query_id' identifies the query, 'ok' indicates success, and 'shipping_options' or 'error_message' provide the response, but this is not stated. 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 clearly states the action ('Reply') and resource ('shipping queries'), distinguishing it from sibling tools like answer_pre_checkout_query. The condition 'Called if sendInvoice used is_flexible' provides additional context, though it could more explicitly state the purpose of approving/rejecting shipping options.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a specific trigger condition ('Called if sendInvoice used is_flexible'), which helps the agent decide when to use this tool. However, it does not explicitly mention when not to use it or compare it with alternative methods such as answer_pre_checkout_query, but the condition is sufficiently clear for basic selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what annotations and the tool name convey. It does not mention that the gift will be consumed, that Stars are credited to the business account, or any side effects or auth requirements. The openWorldHint suggests external effects, but no details are given.
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 very short and to the point, but the inclusion of '(v9.0)' adds noise without value, preventing a perfect score. Otherwise, the single sentence 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?
This is a financial operation (converting a gift to Stars) with no output schema, yet the description provides no information about prerequisites, success behavior, or potential errors. It is not complete enough for an agent to use safely without additional clarification.
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 the meaning of business_connection_id and owned_gift_id solely from their names, which is insufficient for reliable tool 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 clearly states the action ('Convert a gift') and the result ('to Telegram Stars'), with a specific verb and resource. It distinguishes from sibling tools like upgrade_gift and transfer_gift by focusing on conversion to Stars.
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, nor any prerequisites or exclusions. The context signals show many related gift tools, and the description does not help select between them.
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 merely repeats the tool's name and adds a version tag. It does not disclose any behavioral traits beyond the annotations, such as irreversibility or required business connection.
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 phrase 'Delete a story' is succinct and front-loaded. However, the parenthetical '(v9.0)' adds no informational value and slightly detracts from 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?
Given the lack of output schema and minimal description, the tool is under-specified. It does not explain the effect of deletion, error conditions, or relationship to business accounts, making it incomplete 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?
The input schema has 0% description coverage, and the description provides no explanation of story_id or business_connection_id. The agent is left without semantic guidance for these 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 a specific action ('Delete') on a specific resource ('a story'), which distinguishes it from sibling tools like edit_story or repost_story. It is direct 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 versus alternatives, such as delete_message or delete_business_messages. The description lacks context about prerequisites, ownership, or 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 annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds no further behavioral context, such as whether changes are reversible or what actually gets edited beyond the verb 'Edit'. It does not contradict the annotations, but it also does not enrich them.
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 sentence with no wasted words, making it concise, but it is under-specified. While the front-loaded structure is fine, the extreme brevity fails to convey essential usage or parameter context, so it is not appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a write operation with no output schema and sparse parameter descriptions. The description does not explain what aspects of the subscription invite link can be edited, how it differs from regular invite link editing, or any side effects. Given the available annotations and schema, the description leaves significant gaps for the agent to operate 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 only 33% (only chat_id is described). The description names the resource but does not explain what 'name' or 'invite_link' parameters do in this context. With low schema coverage, the description should compensate, but it does not, leaving the semantics of two parameters entirely to inference.
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 a specific verb 'Edit' and a specific resource 'subscription invite link', which clearly distinguishes it from the sibling tool 'edit_chat_invite_link' that edits regular invite links. However, it is minimal and does not mention the chat context explicitly, though the resource name is fairly 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?
The description provides no guidance on when to use this tool versus alternatives such as 'edit_chat_invite_link' or 'create_chat_subscription_invite_link'. There is no mention of prerequisites, exclusion criteria, or preferred scenarios, 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.
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 safe read behavior is known. However, the description adds no behavioral context beyond the annotations, such as pagination behavior, ordering, or what constitutes a transaction. It does not contradict annotations, but it provides no extra value.
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 zero wasted words. It directly states the tool's purpose and nothing more, making it highly concise and easy to parse.
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 is too terse to be fully complete. It does not define what a 'transaction' entails, whether the result is a list, or how pagination works, despite having no output schema to clarify return values. The lack of context about related star tools also reduces 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?
The schema has two parameters (limit and offset) with 0% description coverage in the input schema. The description does not mention or explain these parameters, leaving the agent to infer their meaning from names alone. With low schema coverage, the description needed to compensate but did not.
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 'Get the bot's Telegram Star transactions' clearly identifies the action (get) and the resource (bot's Telegram Star transactions). It is specific enough to distinguish from the sibling get_my_star_balance (which gets balance, not transactions), though it does not explicitly name 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 related star management tools like get_my_star_balance or get_business_account_star_balance. The description gives no context for selecting this over alternatives, and there are no exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint false, covering safety. However, the description adds no behavioral context beyond what annotations provide—it doesn't mention pagination, response format, or any side effects. It merely restates 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, clear sentence with no unnecessary words, achieving maximum conciseness. While it is minimal, it is appropriately front-loaded for a simple getter, though it sacrifices informativeness.
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 no output schema, the description should explain return values, but it only says 'photos' without specifying the structure or whether it's a list. It also omits pagination details despite limit/offset params. Annotations cover safety but not functionality, leaving the tool incomplete for confident invocation.
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. It doesn't mention that user_id is required or what limit and offset control. The description fails to compensate for the lack of schema descriptions, leaving parameter semantics entirely to inference.
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 'Get' and the resource 'user's profile photos', which is specific and distinguishes it from sibling tools like get_user_profile_audios and set_my_profile_photo. It directly conveys what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no context on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. It simply states the action without guidance on selection among 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 already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds no extra behavioral context beyond restating the action, such as side effects, reversibility, or impact on unread counts, failing to add 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. While extremely concise, it sacrifices informative content, but as a stylistic element it is appropriately 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?
Given three required parameters, no output schema, and low schema description coverage, the description is inadequate. It doesn't clarify the purpose of business_connection_id, how to obtain it, or what 'mark as read' changes, leaving the agent without enough information for reliable invocation.
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 only 33% (chat_id has a description; business_connection_id and message_id do not). The tool description does not compensate for this gap; it offers no explanation of the parameters' roles or formatting, making correct invocation challenging.
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 'mark' and resource 'business message as read', clearly distinguishing it from siblings like delete_business_messages or set_message_reaction. The operation is unambiguous and directly conveys its intent.
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, nor any mention of prerequisites or exclusions. The description simply states the action without contextual placement among sibling 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?
The annotations already indicate destructiveHint=true and readOnlyHint=false, so the agent knows this is a destructive write operation. However, the description adds nothing beyond the word 'revoke'—it does not state that the link becomes permanently invalid or that the action is irreversible. Since the annotations cover the safety profile, the description contributes minimal 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 sentence with no filler, making it very concise and front-loaded with the essential action. However, it is so brief that it omits important context, though that brevity is not a penalty for this dimension alone.
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 destructive tool with no output schema, the description lacks contextual information about effects, prerequisites, or when to use it. The presence of related sibling tools like edit_chat_invite_link highlights these omissions. The description is minimally viable but not complete for an agent deciding between similar operations.
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 a description for chat_id but not for invite_link, leaving 50% of parameters undocumented. The description 'Revoke an invite link' does not clarify the meaning or format of either parameter, failing to compensate for the schema's gap. It adds no semantic value beyond what the parameter names already convey.
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 'revoke' and identifies the resource as 'invite link', clearly distinguishing this action from sibling tools like create_chat_invite_link, edit_chat_invite_link, and export_chat_invite_link. Despite its brevity, 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 edit_chat_invite_link. The description does not mention prerequisites, use cases, or situations where revoking is preferred over editing or creating a new link. This is a significant gap for a destructive operation.
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 add behavioral context beyond the annotations. It fails to disclose that the 'username' parameter is optional in the schema, which likely means omitting it could clear the username, nor does it mention uniqueness constraints or side effects. The annotations already cover read-only/mutation status, so this adds little value.
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 or unnecessary wording. It is front-loaded and easy to parse, though it sacrifices content 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?
Given the minimal schema (no parameter descriptions), no output schema, and the availability of closely related sibling tools, the description is too sparse. It lacks operational details such as how to obtain the business_connection_id, whether username can be omitted, and how this action fits with other business account settings.
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 compensate. It mentions 'username' but does not explain the required 'business_connection_id' parameter, its purpose, or the optional nature of 'username'. The one short sentence provides no meaningful parameter semantics beyond what the parameter names already imply.
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 the username of a business account' uses a specific verb and resource, clearly indicating the operation. It distinguishes itself from sibling 'set_business_account_name' by targeting the username rather than the display 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 set_business_account_name, nor any prerequisites or exclusions. The only implied context is that it is for setting a username, but no direct comparison or decision framework 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?
The annotations already indicate a write operation (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds no additional behavioral context, such as the requirement for administrative rights, error conditions, or that it replaces any existing title. Thus it fails to disclose traits beyond what structured metadata already conveys.
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 one short sentence with no filler, front-loading the core action. It is highly concise and free of unnecessary 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?
For a three-parameter setter with no output schema, the description is too sparse to be contextually complete. It lacks information about expected behavior, return value, prerequisites, or error scenarios, leaving the agent to infer critical details from the tool name alone.
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 covers two of three parameters with descriptions; custom_title only has maxLength. The description adds no meaning beyond the parameter names and simple action statement. It does not clarify the format or constraints of the custom title beyond the schema's maxLength.
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 a custom title for an administrator.' It identifies the resource (administrator) and the operation (set custom title), making the tool's purpose unambiguous. While it doesn't explicitly contrast with sibling tools like set_chat_title, the focus on 'administrator' inherently differentiates it.
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, prerequisites, or alternatives. It does not mention that it requires the user to already be an administrator, or that it only works in appropriate chat types. No exclusions or context 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?
Annotations indicate readOnly=false, idempotent=true, and destructive=false, but the description adds little beyond 'shown in the menu'. It does not disclose whether the command list replaces existing commands, how scope affects behavior, or any 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 clear sentence with no redundancy or filler. It is appropriately sized for the tool's simple purpose.
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 description is severely incomplete given the tool has three undocumented parameters and no output schema. It fails to explain the meaning of scope and language_code, or what response to expect, leaving the agent without enough information to 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 coverage is 0%: the description does not explain any of the three parameters (scope, commands, language_code). Even 'commands' is only vaguely implied by 'command list', and scope/language_code are completely omitted.
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 'Set' and the resource 'bot's command list', with the added context 'shown in the menu' which distinguishes it from get_my_commands and delete_my_commands. 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?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that get_my_commands reads the current list or delete_my_commands removes it, nor does it clarify scope/language usage contexts.
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 the annotations already provide. Annotations indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, and the description merely says 'Change' without elaborating on effects, reversibility, or required permissions.
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, succinct sentence with no unnecessary words. It is well-structured and front-loaded, but it could be more informative 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?
Given the two-parameter tool with no output schema and no parameter descriptions, the description is too minimal to be complete. It doesn't specify valid values for mask_position or how it should be formatted, leaving the agent uncertain about how to 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% for both parameters. The description does not explain what 'mask_position' accepts (e.g., coordinates, string, percentage) or how 'sticker' should be specified. It adds no value to 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 clearly states a specific action ('Change the mask position') on a specific resource ('mask sticker'). It distinguishes itself from sibling tools like set_sticker_position_in_set because it refers to the mask position, not the position within a sticker set.
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 any exclusions, prerequisites, or when a different sticker-modification tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations. It does not disclose what happens if the 'thumbnail' parameter is omitted (e.g., whether it clears the thumbnail), any auth requirements, or side effects. Annotations already indicate readOnlyHint=false and idempotentHint=true, but the description carries no extra insight.
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 states the purpose with no filler or redundancy.
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 three parameters, no output schema, and no usage guidance, the description is too minimal. It does not cover important context such as what the 'user_id' refers to, how to specify the thumbnail, or how this differs from the custom emoji counterpart.
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 only 33%, with only the 'thumbnail' parameter having a description. The description itself provides no additional meaning for 'name' or 'user_id', and the parameter names are not fully self-explanatory in the context of a sticker set operation.
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 action ('Set') and the target resource ('thumbnail of a sticker set'), making the tool's purpose specific. However, it does not explicitly distinguish this from the sibling tool 'set_custom_emoji_sticker_set_thumbnail', though the wording implies regular sticker sets.
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 custom emoji sticker sets should use the sibling tool, nor does it clarify prerequisites like ownership or permissions.
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 convey non-read-only, non-destructive, and idempotent behavior. The description adds no extra context about side effects, ownership changes, or requirements, such as the need for a business connection. It essentially restates the tool 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 very short and front-loaded, which is good for conciseness. However, the parenthetical '(v9.0)' is unnecessary fluff and does not enhance understanding, slightly reducing the 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?
This is a mutation tool with three required parameters and no output schema. The description is too sparse to be complete, especially given the many gift-related sibling tools. It fails to explain the role of business_connection_id or the implications of transferring a gift.
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?
With 0% schema description coverage, the description must compensate, but it does not mention any of the three required parameters (business_connection_id, owned_gift_id, new_owner_chat_id). No meaning is added beyond the parameter names themselves.
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 specific action 'Transfer a gift' and the recipient 'to another user', effectively distinguishing it from siblings like send_gift. The version marker 'v9.0' is minor but does not confuse the core purpose.
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_gift or convert_gift_to_stars. The description lacks any indication of prerequisites, exclusions, or typical use cases.
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=false, destructiveHint=false, and idempotentHint=true, so the safety profile is known. However, the description adds no behavioral context beyond the annotations, such as what 'upgrade' entails, whether it changes the original gift, or any side effects. The version marker '(v9.0)' is non-behavioral.
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 immediately conveys the core action. It is not verbose or padded, but it is extremely short and leaves out additional context that could be included without harming 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 mutating operation with two parameters, no output schema, and no parameter documentation, this description is critically underwhelming. It does not explain the business connection requirement, the nature of 'unique gift,' or the expected result, leaving the agent with too little information to use the tool confidently.
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 either parameter (owned_gift_id, business_connection_id). The description entirely fails to compensate for the lack of schema documentation, leaving parameter semantics to be guessed from 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 uses a specific verb ('Upgrade') and resource ('a gift') and clarifies the target state ('to a unique gift'), clearly distinguishing it from sibling tools like send_gift, convert_gift_to_stars, and transfer_gift. The version annotation '(v9.0)' adds a minor but unambiguous reference.
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 many gift-related siblings (e.g., send_gift, convert_gift_to_stars, transfer_gift). There is no mention of prerequisites, context, or exclusions, leaving the agent to infer appropriate 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?
Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds no extra behavioral context such as side effects, permission requirements, or what 'approve' entails. It does not contradict annotations, but it also does not go beyond them. For a mutating action, this is a gap in 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 sentence, front-loaded with the verb and resource. It wastes no words and is easily parsed. The inclusion of '(v9.2)' is a minor aside but does not harm readability or structure.
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 lack of parameter semantics and any usage guidance, the description is incomplete for an agent to invoke the tool correctly. It does have clear purpose, but the absence of behavior details, parameter meanings, and decision context leaves significant gaps for such a simple tool.
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 two required parameters but provides no descriptions, and the tool description also fails to explain their meaning or format. business_connection_id and message_id are named, but what message_id refers to (the suggested post?) is not clarified. With 0% schema coverage, the description must compensate, and 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: 'Approve a suggested post for a channel.' It uses a specific verb and resource, and it distinguishes itself from the sibling tool 'decline_suggested_post' by implying the opposite action. The version note '(v9.2)' is extra but does not cloud 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 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 pruning criteria, prerequisites, or scenarios such as 'use decline_suggested_post to reject instead.' The only implied usage comes from the verb, but there is no explicit comparison or exclusion.
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, destructiveHint=false, idempotentHint=true, but the description adds no behavioral context beyond the action. It does not explain side effects, what 'decline' entails, or any required permissions. The version note 'v9.2' is not behavioral.
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 sentence with no fluff, making it concise and front-loaded. However, the version marker '(v9.2)' is somewhat extraneous and adds little value, slightly reducing efficiency.
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 no output schema and only 0% parameter coverage, the description must provide more context. It lacks any details about return values, effects, or usage nuances, leaving the agent without enough information to use the tool appropriately.
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%, but the description provides no information about the two required parameters (business_connection_id and message_id). It fails to compensate for the schema's lack of semantic explanation, offering no meaning beyond raw 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 clearly states the action ('Decline') and the target resource ('a suggested post for a channel'), which distinguishes it from the sibling tool 'approve_suggested_post' through the opposing verb. 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly conveys usage (to decline a suggested post) but does not explicitly mention when to use it vs. approving, nor any prerequisites or context. It provides no comparison to alternatives, so guidance is implied rather than explicit.
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, and the description simply restates the action. It adds no additional behavioral context such as irreversibility, permission requirements, or side effects beyond what the 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 a single, clear sentence with no filler or redundancy. It is front-loaded and 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?
For a simple one-parameter destructive tool, the description is incomplete: it lacks any context about the 'sticker' parameter, usage restrictions, or relationship to sibling tools. The low schema coverage and absence of output schema place the burden on the description, which it does not meet.
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 one parameter 'sticker' with 0% description coverage, and the description does not explain what this parameter should contain (e.g., a file identifier, sticker ID, or set placement). The description adds no value beyond the parameter name itself.
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 'Delete a sticker from a set.' clearly states the action (delete) and the resource (a sticker from a set). It distinguishes from sibling 'delete_sticker_set' by specifying removal from a set rather than deleting the entire set.
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. It does not mention prerequisites, such as the sticker set existing or the sticker being currently in the set, nor does it point to sibling tools like 'delete_sticker_set' for deleting an entire set.
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=false, destructiveHint=false, and idempotentHint=true, but the description adds no extra behavioral context. It does not mention requirements like bot permissions, error cases (e.g., message not found or no inline keyboard), or the handling of inline_message_id versus chat_id+message_id, which would be valuable 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: 'Edit the inline keyboard of a message.' It avoids redundancy and gets to the point, earning high marks for efficiency, though it may be slightly too terse for the tool's complexity.
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 4 parameters, multiple reply_markup types, and an alternative inline_message_id, the tool has notable complexity, but the description provides only one line. It fails to explain when to use this vs sibling edit_message_* tools, how to remove a keyboard, or how inline messages are targeted. The context is incomplete for an agent to invoke it correctly, despite annotations providing some safety context.
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 descriptions cover 75% of parameters (chat_id, message_id, reply_markup), and the description does not add meaningful detail about these parameters or the undocumented inline_message_id. It neither clarifies parameter usage nor compensates for the missing schema description of inline_message_id, so it provides only marginal additional value.
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 a specific verb 'edit' and identifies the resource 'inline keyboard of a message', which distinguishes it from sibling tools like edit_message_text or edit_message_caption. However, it says 'inline keyboard' while the reply_markup parameter accepts broader keyboard types (ReplyKeyboardMarkup, ReplyKeyboardRemove, ForceReply), slightly narrowing the actual scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/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 edit_message_text, edit_message_caption, or other message editing tools. There is no mention of use cases, exclusions, or prerequisites, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 agent knows this is a mutation. The description adds that it can cancel or extend a subscription, which is useful but does not disclose side effects (e.g., changes to user's access, payment implications) or what happens with the given telegram_payment_charge_id. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action. It earns its place with no filler, though it is arguably too brief for the tool's complexity.
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 three required parameters, no output schema, and the complexity of subscription management, the description is insufficient. It does not explain return values, the role of telegram_payment_charge_id, or how to specify an extension. The tool name and schema leave significant gaps that the description should fill.
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?
Only user_id has a schema description (33% coverage). The description adds a hint that is_canceled likely controls cancel vs. extend, but it does not explain telegram_payment_charge_id or the exact boolean semantics. 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool edits a user's Star subscription and specifies the two modes (cancel or extend). It uses a specific verb and resource, which differentiates it from siblings like refund_star_payment. However, it lacks detail on what 'extend' entails, leaving some 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 such as refund_star_payment or create_chat_subscription_invite_link. The description gives no context about prerequisites, typical scenarios, or exclusions, leaving the agent to infer usage from the name and schema.
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 and destructiveHint=false, so the write nature is known without the description. The description adds the business-account scope and version, but it does not disclose behavioral details such as required permissions, content validation, or response behavior. It is consistent with annotations and provides modest additional 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 short sentence with no filler, front-loading the primary action. It is concise and well-structured, but for a tool with nine parameters and no parameter documentation, the brevity may sacrifice essential guidance. Still, as a purpose statement, it is appropriately compact.
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?
This is a write operation with two required parameters, no output schema, and no parameter descriptions. The description only states the overall action and does not explain required arguments, response format, or relationships to related story tools, so it is far from complete given the tool's complexity.
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 names no parameters. The phrase 'on behalf of a business account' loosely points to business_connection_id, but required parameters like active_period and optional fields like content, caption, parse_mode, and protect_content are entirely unexplained, forcing the agent to guess their meaning and format.
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 'Post' with the resource 'a story' and clearly scopes it to 'on behalf of a business account.' This distinguishes it from sibling tools like edit_story, delete_story, and repost_story, making the tool's core function immediately apparent.
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 such as edit_story or delete_story, nor does it mention prerequisites like having a valid business_connection_id or active_period. It provides no when-to-use, when-not-to-use, or alternative references, leaving the agent to infer usage solely from the tool 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 disclose that this is a non-read-only, non-destructive, and idempotent operation. The description adds no additional behavioral context such as refund limits, timing constraints, or side effects, failing to go beyond the structured data.
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 one short sentence, well front-loaded with the action and target. It is efficient, though so terse that it borders on under-specification rather than polished 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?
For a tool with two required parameters and no output schema, the description is incomplete: it does not explain the meaning of the parameters, any prerequisites, or expected outcomes. The brief statement covers only the high-level action, leaving the agent without enough information to use it 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?
With 0% schema description coverage, the description should compensate for lack of parameter documentation, but it does not. The param names 'user_id' and 'telegram_payment_charge_id' are somewhat self-explanatory, yet no guidance is given on what values to provide or where to obtain them.
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 ('Refund') and a clear resource ('Telegram Star payment'), making the tool's function immediately obvious. It distinguishes itself from sibling payment-related tools like get_star_transactions or get_my_star_balance by indicating a mutating operation.
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, prerequisites, or alternatives. It simply states the operation without any context on eligibility conditions or relationships to other payment 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 disclose that the operation is mutating (readOnlyHint=false) and non-destructive (destructiveHint=false), so the description's statement of removal aligns with them. However, the description adds little beyond that—no mention of what happens when photo_id is omitted, no details on reversibility, and the '(v9.4)' suffix is irrelevant. The description is consistent with annotations but does not significantly enrich 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded, but the '(v9.4)' suffix is unnecessary noise. It does not waste many words, but it also does not earn every word since the version number adds no value. It is appropriately short, yet slightly under-specified.
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 simplicity of the tool, the description is minimal but leaves critical gaps: the meaning and behavior of the optional photo_id is unexplained, there is no return value information (no output schema), and there is no linkage to related tools like get_user_profile_photos for retrieving photo IDs. The description does not provide enough context for an agent to use the tool correctly in varied scenarios.
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 one parameter (photo_id) with 0% description coverage, and the description does not mention it at all. There is no explanation of what photo_id refers to, whether it is required, or what happens if omitted. The description completely 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 clearly states the action: 'Remove the bot's profile photo', which distinguishes it from sibling tools like set_my_profile_photo (which adds/updates) and remove_business_account_profile_photo (which targets a business account's photo). The verb 'remove' and resource 'bot's profile photo' 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 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, no mention of prerequisites (e.g., needing the photo_id from get_user_profile_photos), and no context about the optional photo_id parameter. It simply states the action without situational or comparative 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 indicate it's a write operation (readOnlyHint=false) and not destructive, but the description adds only the recipient scope. It fails to disclose that sending a gift likely consumes it, requires a valid gift_id, or that text and pay_for_upgrade options affect the transaction.
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, front-loaded sentence with no fluff, but it is under-specified for a tool with 7 parameters. It is concise at the expense of necessary detail, so it isn't 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?
With no output schema, low schema coverage, and only 11 words, the description leaves out prerequisites (e.g., gift availability), return behavior, and error handling. The sibling tools hint at a larger gift workflow, but this description doesn't connect to that 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?
Schema coverage is only 29%, and the description compensates minimally. It hints at user/channel targeting via 'to a user or channel chat', but leaves gift_id (required), text, pay_for_upgrade, text_parse_mode, and text_entities 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?
Description uses specific verb 'Send' with resource 'gift' and target 'to a user or channel chat', clearly distinguishing it from sibling send_* tools and other gift-related tools like transfer_gift or gift_premium_subscription.
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. It doesn't mention prerequisites like fetching available gifts via get_available_gifts, nor does it contrast with related tools such as transfer_gift or gift_premium_subscription.
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 one behavioral detail: Telegram clients support MPEG4 videos, which is a format constraint. Annotations already indicate it is not read-only, not idempotent, and not destructive. The description does not contradict annotations and provides a small extra context about video format requirements, but omits other behaviors like file size limits or streaming support.
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 sentences with no fluff. The primary action is front-loaded, and the additional sentence adds a relevant format detail. Every word serves a purpose, though the description is under-specified overall.
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?
This is a complex tool with 20 parameters and no output schema, yet the description provides minimal information. It does not explain return values, error conditions, or how parameters interact. The agent is left under-equipped to invoke the tool correctly, especially for optional parameters and edge cases.
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 only 40%, meaning most parameters lack descriptions. The tool description adds no parameter-specific meaning, failing to compensate for the gap. It does not explain key parameters like effect_id, has_spoiler, or supports_streaming, so agents have to infer from names or external knowledge.
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 'Send a video file', which is a specific verb plus resource. It clearly conveys this tool sends videos, but does not explicitly differentiate it from sibling tools like send_animation or send_video_note. However, the resource and action are unambiguous enough for basic selection.
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_animation, send_video_note, or send_media_group. The note about MPEG4 support is a compatibility hint, not usage context. There is no mention of exclusions, prerequisites, or switching conditions.
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 declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, covering the safety profile. However, the description adds no extra behavioral context—such as whether the photo replaces existing photos, requires a business connection, or has other side effects. It contributes nothing beyond the annotations and 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that is front-loaded and contains no filler. It efficiently conveys the core action and resource, achieving maximum conciseness without unnecessary words.
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 tool's apparent simplicity, it has zero schema coverage and no output schema. The description fails to clarify the role of the required business_connection_id, how the photo should be provided, or any usage caveats. An agent would be left guessing about essential invocation details, making the description incomplete.
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%, so the description must compensate by explaining parameters. It does not explain business_connection_id or the photo parameter's format, type, or requiredness. The word 'photo' in the name gives only the most basic hint and is insufficient 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 the specific verb 'Set' and the specific resource 'profile photo of a business account', which clearly distinguishes it from sibling tools like set_my_profile_photo and set_chat_photo. It precisely identifies the target without 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 such as set_my_profile_photo or remove_business_account_profile_photo. It does not mention the need for a business connection, nor does it exclude use cases. The description offers no contextual usage direction beyond the action itself.
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 convey that this is a state-changing (readOnlyHint=false), idempotent, and non-destructive operation. The description adds no further behavioral context, such as irreversibility, permissions, or side effects, and essentially restates the tool name.
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 with no wasted words. It is front-loaded and concise, earning a top score for brevity even though it lacks depth.
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 description fails to distinguish a regular forum topic from the general forum topic, which is a critical distinction given the sibling tool. It also does not mention return values or any other relevant context, leaving the description incomplete for a tool that could be easily confused with its sibling.
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 100%, with both parameters (chat_id, message_thread_id) clearly described in the schema. The description does not add additional parameter semantics, but the schema is sufficient, warranting the baseline 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 identifies the action (unpin) and target (all messages in a forum topic), which is sufficient for basic understanding. However, it does not explicitly distinguish this from the sibling unpin_all_general_forum_topic_messages, although the schema's message_thread_id and the tool name imply 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?
No guidance is provided on when to use this tool versus alternatives such as unpin_all_general_forum_topic_messages or unpin_chat_message. The description simply states what it does without any contextual selection 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 indicate the operation is not read-only, is idempotent, and not destructive, but the description adds no additional behavioral context. It fails to explain what 'verify' entails, whether it can be undone, or any permissions required. The description merely restates the action without enriching 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff, making it concise. However, it is under-specified, omitting critical details about usage, parameters, and effects. It balances brevity and completeness poorly, leaning too far toward 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?
With no output schema, the description should explain what the tool returns, but it does not. It also lacks any information about the verification workflow, potential errors, or how it relates to sibling verification tools. For a tool that modifies user state, this description is too sparse for an agent to invoke it confidently.
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 provides a minimal description for user_id ('User ID') but no description for custom_description. The tool description does not explain the meaning or purpose of either parameter, leaving half the parameters poorly defined. With only 50% schema coverage and no guidance in the description, parameter understanding 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 ('Verify') and the resource ('a user'), with the qualifier 'on behalf of the bot's organization' adding necessary context. It differentiates from sibling tools like verify_chat and remove_user_verification by targeting users 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?
No guidance is provided on when to use this tool versus alternatives such as verify_chat or remove_user_verification. There are no prerequisites, exclusions, or usage context beyond the vague 'on behalf of the bot's organization.'
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 fully covered. The description adds no additional behavioral context beyond what the annotations provide, such as response format or edge cases. This meets the baseline for a read-only tool with 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 a single, concise sentence that is front-loaded and contains no unnecessary words. It efficiently states the tool's purpose without fluff, making it easy to scan.
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 no output schema and one optional parameter, the description is too minimal to be complete. It does not explain the parameter's effect or what the return value will be. For a getter with no structured output documentation, the description should provide more context about the response or usage, which it fails to do.
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 single parameter 'for_channels' is a boolean with no schema description, and the description does not mention it at all. With 0% schema description coverage, the description fails to compensate by explaining what the parameter does or how it affects the results. The parameter name offers some hint, but the description leaves it unexplained.
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 'Get default admin rights' clearly indicates a read operation to retrieve default administrator rights, matching the tool name and distinguishing it from the sibling setter 'set_my_default_administrator_rights'. However, it does not elaborate on what 'default admin rights' means or who they apply to, so it is clear but not deeply specific.
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. There is no mention of the setter sibling or any context suggesting when this getter is appropriate. The sibling list implies a pair with 'set_my_default_administrator_rights', but the description itself offers no such 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 indicate a mutating, non-idempotent operation, but the description adds no behavioral context such as star deduction, recipient notification, or reversibility. It merely restates the action without disclosing 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no fluff, but it skips important details. It is efficient in length but not in informational 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 three required parameters, sparse schema descriptions, no output schema, and no behavior details, this description is far from complete for a mutating gifting action. It leaves critical 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?
Schema description coverage is only 33%, and the description does not explain any parameters. month_count and star_count are completely undescribed, leaving the agent to guess their meaning and relationship.
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 'Gift' and a specific resource 'Telegram Premium subscription', clearly distinguishing this from sibling tools like send_gift which handles regular gifts. The purpose is unambiguous even though terse.
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 gifting a Premium subscription but provides no explicit guidance on when to use this vs alternatives like send_gift or edit_user_star_subscription. No exclusions or alternatives 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 a mutating (readOnlyHint=false), idempotent, and non-destructive operation. The description adds that it applies to supergroups/channels and involves promotion/demotion, but doesn't disclose important behaviors such as how omitted permission flags are interpreted (likely all false) or the need for admin rights.
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 core function with no wasted words. It is well-structured and easily parsed.
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?
For a tool with 19 parameters and no output schema, this one-line description is severely incomplete. It doesn't explain how permission flags map to promotion/demotion, what happens when no flags are set, or any operational prerequisites, leaving an agent with insufficient context to use it 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?
With 19 parameters and only 11% schema description coverage, the description must compensate, but it mentions no parameters at all. The many boolean permission flags are left completely unexplained, making it impossible to understand their effect from 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 clearly states the action ('Promote or demote'), the target ('a user'), and the scope ('in a supergroup or channel'). This distinguishes it from sibling tools like ban_chat_member or restrict_chat_member and is not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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. While the name implies promotion/demotion, the description does not mention when to prefer it over restrict_chat_member or set_chat_administrator_custom_title, nor any prerequisites like being an administrator.
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, open-world side effects, and the description adds that the tool informs the user of an ongoing action. However, it does not disclose that the effect is a transient status indicator, nor does it explain prerequisites or optional parameter contexts. 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 single, short sentence that is front-loaded with the verb and resource. No unnecessary words or repetition.
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?
There is no output schema and the description does not mention the return value or that the action is a temporary chat status. With low schema coverage and undocumented optional parameters, the description leaves gaps that an agent would need to infer.
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 only 25% (chat_id described). The description gives action examples but these are already enumerated in the schema, and it does not explain message_thread_id or business_connection_id. Thus it fails to compensate for the low 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 tells the user the bot is performing an action, with examples like typing and uploading. It is not a tautology and identifies the resource (the user chat), but it does not explicitly distinguish itself from the many sibling send_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 before sending a message or during a long operation. There is no mention of exclusions, prerequisites, or which sibling tools to prefer.
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 declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the agent knows basic safety characteristics. However, the description adds no behavioral details beyond the purpose—such as the need to respond promptly, the effect of show_alert, or any side effects. It does not contradict annotations, but it also provides little extra 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 sentence with no unnecessary words, and the key action is front-loaded. It is efficient, though it could have included more useful detail without becoming verbose. It earns its place but is minimal.
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, no output schema, and only a one-line description, the tool definition is incomplete for reliable invocation. The description helps with selection (what the tool does) but provides almost no guidance on how to call it correctly—parameter meanings, required fields, or behavioral constraints are all absent.
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 5 parameters with 0% description coverage, and the description mentions none of them. It says nothing about callback_query_id, text, url, cache_time, or show_alert, leaving the agent without any additional meaning beyond the bare property names. The description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Answer') and resource ('callback query'), and clarifies the source ('from an inline keyboard button'). This clearly differentiates it from sibling tools like answer_inline_query, answer_shipping_query, and answer_pre_checkout_query, which handle different query types.
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 'from an inline keyboard button' gives clear context for when this tool is appropriate, but it does not explicitly mention alternatives or when not to use it. It provides a clear context without exclusions, matching a score of 4.
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 readOnlyHint=false and destructiveHint=false, covering the base safety profile. The description adds the 'Max 50 results' limit, which is a useful behavioral constraint. However, it does not elaborate on side effects, caching, or error handling, so the additional context is limited but not absent.
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, direct sentences with no filler. It front-loads the primary action ('Send answers to an inline query') and then states the key limitation, achieving maximum clarity in minimal space.
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 six parameters and no output schema, the description is too sparse to cover the tool's complexity. It omits essential details about result formatting, parameter structure, and when it is appropriate to invoke this method, leaving substantial gaps for an AI agent.
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% for six parameters, so the description must compensate. It only vaguely references 'results' via the maximum count and fails to explain inline_query_id, cache_time, is_personal, next_offset, or button. This leaves the agent with minimal understanding of how to populate the 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 identifies the action ('Send answers') and specific resource ('inline query'), which distinguishes it from sibling tools like answer_callback_query or answer_shipping_query. It also adds a key constraint ('Max 50 results per query'), making the purpose unambiguous and well-scoped.
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 other answer_* tools. The description does not mention alternatives, conditions, or prerequisites, leaving the agent to infer selection solely from the tool name and the phrase 'inline query'.
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 destructive behavior (destructiveHint: true), and the description's 'Delete' matches this without contradiction. However, the description adds no additional behavioral context such as permanence, permissions, or effects on the sender/receiver, offering 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no extraneous words, making it highly concise and front-loaded. It earns its place by stating the core action, though it could be expanded with more context without compromising structure.
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 destructive multi-parameter tool with no output schema, the description is too sparse. It lacks information about the expected return value, the need for a valid business connection, and any side effects or limitations of deleting business messages, leaving significant 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 and no parameter explanations in the description, the agent must rely on the parameter names alone. The description does not clarify what business_connection_id represents or how message_ids should be formatted beyond the schema's type definitions.
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 'Delete business messages' clearly states a specific action (delete) and a specific resource (business messages), distinguishing it from regular message deletion tools and read_business_message. Despite its brevity, it conveys the core function precisely.
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_message or delete_messages. The description doesn't mention the business connection context or any prerequisites, 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.
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 no additional behavioral context (e.g., auth needs or return details), but no extra context is necessary given the simplicity and complete 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 a single concise sentence that directly states the tool's purpose. Every word earns its place with no redundancy or fluff, making it highly efficient and easy to parse.
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 tool's simplicity, there are notable gaps: the language_code parameter is unexplained, and there is no output schema or description of the return value. The annotations are helpful but do not clarify what the tool returns or how the optional parameter affects the result.
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 language_code parameter at all. The agent cannot infer what this optional parameter controls or how it affects the result, so the description fails to compensate for the missing 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 'Get the bot's description' clearly states the action (get) and the resource (bot's description), distinguishing it from sibling tools like set_my_description and get_my_short_description. 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 versus alternatives such as get_my_short_description or set_my_description. There are no explicit usage contexts, prerequisites, or exclusions, leaving the agent to infer usage solely from the tool 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 that this is a non-read-only, non-destructive, idempotent operation. The description 'Remove chat verification' adds no additional behavioral context such as permissions, side effects, or error conditions, so it provides no 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence that immediately conveys the tool's purpose. There is no wasted text, making it optimally concise.
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 simplicity of the tool (one parameter, no output schema) and the presence of annotations, the description is minimally adequate. However, it lacks any mention of return behavior, prerequisites, or edge cases, which could be important for an agent. It is not a rich description but sufficient for a basic mutation.
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 100% and the single parameter 'chat_id' is already described as 'Chat ID or @username' in the schema. The description adds no parameter information, so it does not enhance the schema's meaning. Baseline 3 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 'Remove chat verification' states a specific action (remove) and resource (chat verification), making the tool's purpose clear. It distinguishes from siblings like 'verify_chat' and 'remove_user_verification' by its precise scope, though it does not elaborate on what 'chat verification' entails.
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 simply states the action without context, leaving the agent to infer from the tool name and sibling 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?
The description adds no behavioral context beyond the annotations. It does not disclose side effects, permission requirements, or behavior when the topic is already open. Since the description essentially restates the tool name, it contributes minimal transparency 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 a single, concise sentence with no filler or redundancy. Every word is necessary to convey the core action, making it appropriately structured 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 simplicity, the complete schema, and annotations indicating idempotency and non-destructiveness, the description is minimally sufficient. However, it omits important usage context such as permissions and preconditions, which is a noticeable gap for a mutation 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?
Schema coverage is 100%, with both chat_id and message_thread_id fully described. The description does not add any parameter-specific meaning, so it stays at the baseline of 3. No additional semantic details are provided for the parameters.
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 'Reopen a closed topic' clearly states the action (reopen) and resource (a closed topic), making the purpose evident. It does not explicitly differentiate from sibling tools like 'reopen_general_forum_topic', but the tool name provides that distinction.
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. It does not mention preconditions such as the topic needing to be closed or required permissions, nor does it exclude scenarios where reopening is not applicable.
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 minimal behavioral context beyond annotations. It does not disclose potential side effects (e.g., message delivery), failure modes, or that the photo is fetched from the provided reference. With annotations offering little (readOnly=false, openWorld=true), the description carries the burden but fails to elaborate.
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, well-structured sentence that directly states the action and the primary input. It is front-loaded and avoids wasted words.
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 15 parameters and no output schema, this description is under-specified. It does not provide an overview of typical use cases, optional features, or any context to help an agent correctly select and invoke the tool beyond the basic photo and chat_id.
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 only 47%, so the description must compensate for undocumented parameters. It only explains the 'photo' parameter, omitting context for chat_id, caption, reply_markup, parse_mode, and the many optional parameters. This is insufficient given the coverage 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 with a specific verb and resource: 'Send a photo.' It also specifies accepted input formats (file_id, HTTP URL, or absolute file path). This distinguishes it from sibling send_* tools like send_document or send_audio.
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 send_photo versus alternatives (e.g., send_document for larger files, send_media_group for multiple photos). The description focuses only on how to pass the photo, not on the decision 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?
Annotations already cover non-destructive and non-read-only status. The description adds feature details (e.g., shuffle, user-added options) but does not disclose message delivery side effects, permission needs, or that the poll can later be stopped, leaving some behavioral ambiguity.
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 that front-loads the primary purpose and highlights key features. It is appropriately sized, though it could expand on usage 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?
Given 29 parameters, no output schema, and low schema coverage, the description is far too brief to be complete. It omits essential context about required inputs (question, options), quiz-specific behavior (correct_option_ids), and return values, leaving the agent underinformed for a complex 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?
With only 31% schema description coverage, the description must compensate, but it only hints at a few boolean features (allows_revoting, shuffle_options, allow_adding_options, description, allows_multiple_answers). Core parameters like options, correct_option_ids, and reply_markup remain unexplained, so the agent must infer their roles.
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 action ('Send') and the resource ('poll or quiz'), and enumerates specific capabilities such as revoting and multiple correct answers. However, it does not explicitly contrast with sibling send tools, relying on the name for differentiation.
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 use case: creating polls or quizzes. Yet it provides no explicit guidance on when to prefer this over send_message or how it relates to stop_poll, leaving usage context mostly 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?
Annotations indicate a write operation that is idempotent and non-destructive, but the description adds no additional behavioral context, such as effects on existing settings, permission requirements, or what the configuration actually changes. The description merely restates the purpose without enriching the behavioral profile.
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 precise sentence with no redundancy, entirely focused on the tool's primary purpose. It is front-loaded and appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the minimal description and lack of parameter details, the description is insufficient for an agent to fully understand the tool's behavior, especially the semantics of 'accepted_gift_types'. While annotations and schema provide some context, the description does not compensate for the schema's 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 has 0% description coverage, and the description does not explain any of the three parameters, including the ambiguous 'accepted_gift_types' which lacks a defined type in the schema. The description provides no semantic value beyond what the parameter names might suggest.
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 'Configure' and resource 'gift settings for a business account', distinguishing it from other business account setters. It is unambiguous and directly reflects 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?
The description implies usage for configuring gift settings, and the purpose is distinct from sibling tools. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide 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 description adds no behavioral context beyond what annotations already declare (readOnlyHint=false, idempotentHint=true, destructiveHint=false). It does not mention permissions, side effects on existing data, or behavior when the description parameter is omitted. With annotations present, the bar is lower, but the description still contributes nothing beyond the literal action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the tool's purpose with no superfluous content. It is appropriately front-loaded and easy to parse.
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?
This is a simple two-parameter tool, but the description is too terse. It fails to convey that the description parameter is optional, nor does it explain expected behavior when omitted (e.g., clearing the description). No permissions or chat-type restrictions are mentioned, leaving notable 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?
The schema describes chat_id with 'Chat ID or @username' and description with type and maxLength, but the description parameter lacks a semantic explanation. The tool description does not clarify the meaning or usage of the parameters, so it fails to compensate for the 50% schema coverage 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 'Change the description of a chat.' uses a specific verb ('Change') and clearly identifies the resource ('description of a chat'). It distinguishes itself from sibling tools like set_chat_title and set_chat_photo, which target different attributes.
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 any context about permissions, prerequisites, or exclusions. It merely states the action, leaving the agent without support for selecting between comparable set_chat_* 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 already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds no extra behavioral context such as whether the old photo is replaced, permission requirements, or side effects. It neither contradicts nor enriches 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?
One short, front-loaded sentence 'Set a new chat photo.' contains no unnecessary words and is appropriately concise for a simple 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?
For a simple 2-parameter mutation with full schema coverage and annotations, the description is minimally adequate. However, it lacks usage context (e.g., when to choose this over similar tools), permissions, and return-value information (no output schema). It is not misleading but leaves some gaps.
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 100%: both parameters have descriptions ('Chat ID or @username' and 'File ID, HTTP URL, or absolute file path'). The description adds no additional parameter meaning, so a baseline of 3 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 'Set a new chat photo' clearly states the action (set) and resource (chat photo), which distinguishes it from sibling tools like delete_chat_photo. However, it does not explicitly differentiate from other chat-setting tools or specify scope (e.g., group vs channel), so it is clear but not fully distinguishing.
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 set_business_account_profile_photo or set_chat_title. No prerequisites (e.g., admin rights) or exclusion criteria are mentioned, 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what annotations provide. It doesn't mention side effects, prerequisites, or permissions. Annotations already indicate it's a non-destructive, idempotent write; the description merely restates the function.
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 sentence with no unnecessary words. It is concise 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 mutation tool, the description is too sparse. It omits key context such as the requirement for the bot to be an administrator, that the sticker set must be a custom set created by the bot, and that the operation replaces any existing sticker set. No output schema exists to clarify return values.
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 coverage is 50% (only chat_id has a description). The description does not explain what sticker_set_name should be or its format. It fails to compensate for the missing schema 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 clearly states the action (Set), the resource (sticker set), and the scope (supergroup). It distinguishes from sibling delete_chat_sticker_set by using 'set' rather than 'delete'.
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 set_chat_title or delete_chat_sticker_set. The description implies a purpose but doesn't state exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate that this is a non-read-only, idempotent, non-destructive operation. The description adds no further behavioral context, such as whether the thumbnail is replaced, any permission requirements, or side effects. 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 sentence of eight words, front-loads the core action, and contains no unnecessary information. It is appropriately concise.
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 low schema coverage and absence of an output schema, the description is too minimal to fully inform the agent. It does not explain parameter meanings, expected behavior, or any context such as whether the sticker set must already exist. It leaves gaps for a tool with two parameters.
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 two parameters. Although 'name' and 'custom_emoji_id' are somewhat self-explanatory from the tool name, the description provides no explicit mapping or expected format, failing 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Set') and a specific resource ('thumbnail of a custom emoji sticker set'), making it clear what the tool does. It is naturally distinguished from sibling tools like set_sticker_set_thumbnail by the explicit mention of 'custom emoji'.
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 information about when to use this tool versus alternatives, no prerequisites, and no exclusions. It is a bare statement of function with no usage 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 declare readOnlyHint=false and destructiveHint=false, so the non-destructive mutation is known. However, the description adds no further behavioral context, such as that the message remains intact, that updates cease permanently, or that ownership/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, direct sentence with no superfluous words. It is appropriately front-loaded and easy to parse, which is ideal 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?
With 4 parameters, 0 required, no output schema, and no usage guidance, the description alone is insufficient for an agent to confidently invoke the tool. The parameter combination logic and expected behavior are not disclosed, making successful use reliant on external knowledge.
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 75%, so the schema already documents most parameters, but the description itself adds no parameter meaning. It does not clarify the alternative between chat_id+message_id and inline_message_id, nor why no parameters are required, leaving ambiguity for 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 'Stop' and a clear resource 'a live location message,' which precisely states the tool's function. It distinguishes from the sibling edit_message_live_location by indicating the action is to cease updates rather than modify 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?
The description gives no guidance on when to use this tool over alternatives, such as edit_message_live_location, nor does it mention prerequisites like needing an existing live location message or the chat_id/inline_message_id distinction. 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a mutating but non-destructive, idempotent operation, but the description adds no behavioral context beyond that. It does not disclose ownership restrictions, effects on voters, or what happens if the poll is already closed.
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 six-word sentence with no redundancy. Every word contributes to the meaning, making it highly concise.
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 for a simple tool, critical context is missing: the poll must be active and sent by the bot, and the optional parameters' purpose is unexplained. Annotations and schema partially compensate, but significant gaps remain.
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 only 25% as only chat_id has a description. The description does not clarify message_id, reply_markup, or business_connection_id, so it fails to compensate for the low 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 uses a specific verb ('Stop') and resource ('a poll') plus location ('in a chat'), clearly identifying the action. It distinguishes itself from siblings like send_poll or edit_message_text.
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, nor any prerequisites such as the poll being active or sent by the bot. The description merely 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?
The description simply says 'Delete', which aligns with the destructiveHint annotation but adds no additional behavioral context. It does not explain default scope/language behavior, the effect on existing commands, or any side effects. With annotations already covering destructiveness, the description contributes little 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 that is front-loaded with the action and target. It is efficient, though it could benefit from one additional sentence about parameter defaults or usage context 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?
Given only 2 parameters, no output schema, and sparse annotations, the description is too thin. It does not cover prerequisite conditions (e.g., commands must have been set), what happens if no parameters are provided, or the meaning of 'scope' variations. This is inadequate for safe invocation of a destructive operation.
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 the parameters. It only mentions 'scope and language' without explaining valid values, defaults, or semantics of the empty 'scope' schema property. This is insufficient for an agent to set parameters correctly.
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 resource ('the bot's command list') and includes qualifiers ('for a given scope and language'). It clearly distinguishes from sibling tools like get_my_commands and set_my_commands, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 the tool (to remove commands) but provides no explicit comparison to alternatives. It does not state exclusions or mention that set_my_commands is the opposite operation, so guidance is limited to what can be inferred from the name and 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 declare this as a safe read operation (readOnlyHint, idempotentHint, non-destructive). The description adds no further behavioral context such as return format or error conditions, but 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, clear sentence with no unnecessary words. It is appropriately concise for a simple getter.
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?
While the tool is simple and the description gives the core purpose, it lacks explanation of the optional language_code parameter and any return value expectations. Given the absence of an output schema, this is a minor 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?
The schema has one optional parameter (language_code) with 0% description coverage. The tool description does not mention this parameter or its purpose, leaving the agent without guidance on how to use it.
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') and the resource ('the bot's short description'), which is specific and distinguishes it from siblings like get_my_description or set_my_short_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?
No guidance is provided on when to use this tool versus alternatives, nor any exclusions or prerequisites. The description is self-contained but lacks explicit 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 information beyond the annotations. It simply restates the operation implied by the name, with no mention of permissions, irreversibility, side effects, or return behavior. The openWorldHint: true annotation further underscores that additional effects are undisclosed.
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, front-loaded sentence with no wasted words. It is concise, though perhaps too sparse to convey meaningful guidance. Still, for this dimension it performs well.
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 low complexity (one parameter, clear schema, and annotations), the description is minimally viable. However, it lacks any context about preconditions, side effects, or what the tool returns, leaving some gaps in the overall picture.
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 sole parameter user_id is fully described in the schema as 'User ID', giving 100% coverage. The description adds no additional parameter semantics, but the schema already provides adequate information, so a baseline score of 3 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 'Remove user verification' uses a specific verb (remove) and resource (user verification), making the tool's purpose immediately clear. It also distinguishes from sibling tools like verify_user and remove_chat_verification by specifying 'user' rather than 'chat'.
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 verify_user or remove_chat_verification, nor does it state prerequisites or conditions under which removal is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, etc. The description adds the useful behavioral detail about the music player display. No contradictions found. It does not disclose potential side effects, permission requirements, or error behavior, but the annotations lower the bar, so 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 two sentences, front-loaded with the core purpose, and adds one valuable behavior note. Every word earns its place, making it highly concise and efficiently structured.
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's complexity (17 parameters), low schema description coverage, and lack of output schema, this minimal description is insufficient. It does not cover return values, error cases, formatting specifics, or any context beyond the basic send action. For a complex tool, more context is needed to enable 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?
Schema description coverage is only 47%, so the description should compensate for undocumented parameters. It does not; it provides no additional meaning for any of the 17 parameters, not even the required ones beyond what the schema already states. The description is silent on parameter semantics.
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 'Send an audio file', which is a specific action on a resource. However, it does not explicitly distinguish itself from sibling tools like send_voice or send_document. The mention of the music player offers a subtle differentiator but stops short of naming alternatives.
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 noting that Telegram clients display the audio in the music player, suggesting this is for music/audio tracks rather than voice messages. However, it does not explicitly state when to use this tool versus send_voice or send_document, nor any 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 only indicate readOnlyHint=false and destructiveHint=false, and the description adds no extra behavioral context. It does not explain what happens when media is sent (e.g., whether a 'Buy' button appears, if the message is editable, or if any special permissions are required). The description is too minimal to disclose meaningful behavior beyond 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundancy or filler. It is front-loaded with the key action and resource. Every word contributes meaning.
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?
This tool has 16 parameters, low schema coverage, and no output schema, yet the description provides only the barest idea of its function. It does not explain supported media types, return values, errors, or any edge cases. Given the tool's complexity, the description is severely inadequate for an AI agent to invoke it 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 only 38%, and the description does not compensate. Key parameters like 'media' and 'star_count' are undefined in the schema and the description gives no hints about their format or semantics. The only clue is the word 'paid media' which implies stars, but it does not explain how star_count is used.
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 ('paid media') with a clear condition ('requires Stars payment to view'). It clearly distinguishes this tool from the many other send_* siblings, as none of them mention paid media or Star payments.
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 use case (sending media that must be paid for with Stars) but offers no explicit guidance on when to choose this over alternatives like send_photo or send_invoice. There are no when-not-to-use or exclusion details.
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 imply. Annotations state readOnlyHint=false and idempotentHint=true, but the description does not clarify side effects, permissions, or behavior on non-banned users. 'Previously banned' only implies a precondition.
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 is concise and direct. It contains no fluff or redundant details, earning high marks for economy of language.
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 nature of the tool, the description conveys the core action, but lacks guidance on usage context, return values (no output schema), and the purpose of the optional parameter. It is minimally viable but incomplete.
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 describes chat_id and user_id, but the optional 'only_if_banned' parameter lacks any description in both schema and description. The description itself adds no parameter meaning, leaving a gap despite 67% 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 'Unban a previously banned user' clearly states the action (unban) and resource (a user in a chat). It distinguishes itself from the sibling tool 'unban_chat_sender_chat' which unbans a chat instead of a user.
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 'ban_chat_member'. It does not mention prerequisites such as admin rights or that it should only be used for users currently banned.
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 the tool mutates state (readOnlyHint=false) but is idempotent (idempotentHint=true). The description adds no behavioral context beyond the literal action, such as effects on the user's request status or required permissions.
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, clear sentence with no fluff. It effectively states the tool's purpose without unnecessary words.
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 two-parameter tool with good annotations and schema coverage, the description is minimally adequate. However, it lacks context about when to use it (e.g., pending join requests) and what the consequences are, which would improve completeness.
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 covers 100% of parameters with clear descriptions (chat_id and user_id). The description adds no additional parameter semantics, but the baseline of 3 is appropriate given high 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 'Decline a chat join request' uses a specific verb ('decline') and a specific resource ('chat join request'). It clearly distinguishes from sibling tools like 'approve_chat_join_request'.
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 it should be used for pending join requests, or that it requires admin privileges, or any exclusion criteria.
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 the operation is non-readonly, idempotent, and non-destructive. The description adds the useful constraint that only non-primary links can be edited, but does not disclose other behavioral traits such as whether existing join requests are affected or if the link URL remains unchanged.
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 filler words. It is front-loaded and easy to parse, earning its place without redundancy.
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's moderate complexity (6 parameters) and the availability of related invite-link tools, the description is too sparse. It does not explain return values, the effect on the existing invite link, or necessary permissions, making it insufficient for fully informed tool invocation.
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?
With schema coverage at only 17% (only chat_id has a description) and no parameter information in the tool description, the agent is left to infer meaning from parameter names alone. The description does nothing to explain the purpose or constraints of fields like expire_date, member_limit, creates_join_request, or their interaction during an edit.
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 ('Edit') and the resource ('a non-primary invite link'), and the qualifier 'non-primary' distinguishes it from related invite-link tools like export_chat_invite_link or revoke_chat_invite_link.
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 implicitly restricts usage to non-primary invite links, but it does not explicitly say when to use this tool versus creating or revoking a link, nor does it mention any prerequisites like admin rights.
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 and idempotentHint, so the description need not restate safety. It adds the semantic that the gifts are specifically for a business account, but no additional behavioral details like pagination, ordering, or response format are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no unnecessary words. It is front-loaded with the core action and resource, making it highly concise.
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 no output schema and only a minimal description, the tool lacks context on return structure, optional parameter effects, and potential limitations. The description is too sparse to be fully usable without external knowledge.
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 input schema has zero description coverage, and the description mentions no parameters. It does not explain what business_connection_id or exclude_from_blockchain mean, leaving the agent without any guidance for filling these fields.
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 gifts received by a business account. The specific verb 'get' and resource 'gifts' with the scope 'business account' distinguish it from sibling gift tools like get_user_gifts and get_chat_gifts.
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 querying gifts on a business account, but does not explicitly state when to prefer it over alternatives like get_user_gifts or provide exclusions. No usage conditions or prerequisites are given beyond the resource itself.
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 no behavioral context beyond what annotations already provide (non-read-only, idempotent, non-destructive). It does not mention side effects, required permissions, or the reversibility of the action, but 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, concise sentence that states the action without any fluff. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for a basic action, but it lacks context on when to hide versus close the general topic and does not mention admin requirements. The annotations and schema help, but there remains a gap in differentiating from similar sibling 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 only parameter, chat_id, is fully described in the schema as 'Chat ID or @username'. The description does not mention parameters, but schema coverage is 100%, so the schema carries the burden.
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 a specific verb 'Hide' and identifies the resource as 'General' topic, clearly stating the action. It is distinct from siblings like unhide_general_forum_topic (opposite) and close_general_forum_topic, though it does not explicitly differentiate 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?
The description provides no guidance on when to use this tool versus alternatives such as close_general_forum_topic, nor any prerequisites like admin permissions. No contextual usage advice 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?
Beyond the annotations (which already indicate this is a write operation and idempotent), the description adds no behavioral context. It does not disclose side effects like whether the old sticker is permanently removed, whether position is retained, or if the sticker set must be owned by the bot. The description essentially restates 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 10-word sentence, front-loaded with the core action. There is no redundancy or filler, making it arguably the most concise way to state the 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?
The tool is a mutation with no output schema, so the description should cover its full contract. It does not state prerequisites (e.g., set ownership), permissions, return value, or behavioral details like what happens to the old sticker. The description leaves critical context missing for an agent to invoke this 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?
With 0% schema description coverage, the description must compensate, but it only vaguely maps 'existing sticker' to old_sticker and 'new one' to sticker. It does not clarify what 'name' refers to (likely the sticker set name), the expected format of sticker or old_sticker (file_id, sticker object), or the role of user_id. This leaves parameter meanings highly ambiguous.
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 ('Replace') and resource ('an existing sticker in a set'), and it distinguishes the operation from sibling tools like add_sticker_to_set or delete_sticker_from_set. The phrasing is unambiguous and action-oriented.
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 the tool (when a sticker needs to be swapped) but provides no explicit guidance on when to avoid it or which alternative to prefer. There are no mentions of prerequisites, exclusions, or comparisons to related sticker-set operations, so the guidance is only implicit.
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 that the tool is non-read-only (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds the supergroup scope constraint, which is useful, but does not disclose other behavioral aspects like the effect of until_date or how restrictions are applied/removed.
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. It front-loads the verb and scope, making it easy to parse and entirely free of redundancy.
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 and no output schema, yet the description provides minimal context. It omits critical operational details such as the format of permissions, the role of until_date, and any required conditions (e.g., bot permissions, user membership state). This is insufficient for an agent to correctly construct an 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?
With only 40% schema description coverage, the description should compensate for undocumented parameters (until_date, permissions, use_independent_chat_permissions), but it adds no parameter-specific details. It provides no guidance on the structure of permissions or semantics of until_date, leaving the agent to infer from 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 action (restrict), resource (user's permissions), and scope (supergroup). It distinguishes from sibling tools like ban_chat_member and promote_chat_member by focusing on permission modification rather than membership removal or administrative promotion.
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 prerequisites (e.g., bot must be admin), when it should be preferred over ban_chat_member or set_chat_permissions, or exclusions such as applicability only to non-administrator users.
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, idempotent, and non-destructive operation. The description adds context that the result is 'prepared' and destined for an inline button, but does not disclose potential side effects (e.g., overwriting existing saved messages) or any other behavioral nuances.
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 of 14 words, front-loaded with the essential action and purpose. No wasted words or redundant information.
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 6 parameters, no output schema, and very low schema description coverage, the description is too minimal. It omits parameter semantics, usage context, and any mention of return value or behavioral edge cases, making it insufficient for correct invocation.
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 only 17% (only user_id is described). The description does not explain any of the parameters beyond what the schema already provides. The 'result' parameter and the four allow_* boolean flags remain completely undescribed, leaving the agent without guidance on their meaning or usage.
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 ('Save') on a specific resource ('prepared inline message result') with a clear purpose ('for a user to send via inline button'). It distinguishes itself from sibling tools like save_prepared_keyboard_button and answer_inline_query.
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 prepared inline message result to save for a user. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide 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=false, idempotentHint=true, and destructiveHint=false, covering the basic safety profile. The description adds only 'for later use', implying persistence but not explaining side effects, auth, or limits.
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 unnecessary words. It conveys the action and purpose efficiently.
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 annotations, the description is too sparse for an agent to correctly invoke the tool without detailed knowledge of the Telegram Bot API. It omits the format of the 'button' parameter, what the return value is, and how the saved button relates to other tools.
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 describes user_id but leaves the 'button' parameter completely undefined (empty schema, no type or description). The description does not compensate by explaining how the button should be structured or how user_id is used beyond the schema's one-line note.
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 'Save a prepared keyboard button for later use' with a specific verb and resource. It distinguishes itself from sibling tool save_prepared_inline_message by naming the object type as 'keyboard button'.
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 like save_prepared_inline_message. There is no mention of prerequisites, how the saved button is consumed, or any 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 description adds no behavioral context beyond what annotations already provide. It does not mention permissions, side effects, or limitations such as chat type restrictions. While annotations correctly indicate a mutating, non-destructive idempotent operation, the description itself offers 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no fluff or redundant information. It is well-structured and immediately understandable.
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 description is too terse for a real-world operation. It omits important contextual details such as the need for admin rights and that the tool likely only applies to supergroups/channels, not private chats. Without this context, an agent may misuse 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?
Schema description coverage is 50%, with the title parameter having no schema description. The description merely says 'Change the title' without adding meaning to the title parameter or clarifying formats, constraints, or additional details beyond the schema's limited 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 'Change the title of a chat' clearly identifies the action (change) and the resource (chat title), distinguishing it from sibling tools like set_chat_description or set_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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus alternatives, nor are exclusions or prerequisites mentioned (e.g., applicable chat types or permissions). The intended usage is implied but not clarified beyond the action 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=false, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering the safety profile. The description adds domain context ('Telegram Passport elements contain errors') but does not disclose side effects, required permissions, or other behavioral traits such as how the user is informed or what happens on repeated calls.
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, clear sentence with no extraneous words. It is front-loaded with the verb and key information, making it easy to parse. It could benefit from a bit more detail, but it is appropriately concise for the simple purpose it states.
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 only two parameters and no output schema, which reduces complexity. However, the description is too thin to fully understand the 'errors' parameter structure and the exact context in which the tool should be invoked. Annotations help with safety but not semantic completeness, leaving 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?
Schema description coverage is 50%: only user_id has a description. The 'errors' parameter lacks any schema description, and the tool description does not compensate by explaining the structure or meaning of 'errors'. This leaves a significant semantic gap 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 clearly states the tool's function: 'Inform a user that some Telegram Passport elements contain errors.' The verb 'Inform' and resource 'user' specify the action and target, and the domain (Telegram Passport errors) distinguishes it from all sibling tools, none of which perform this task.
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 prerequisites, context, or exclusion criteria. It simply states what the tool does without contextual usage direction.
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 mutating, non-destructive, idempotent operation. The description only restates 'Change' and adds no additional behavioral context (e.g., whether the list is replaced wholesale, validation rules, or ownership 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 sentence with 10 words, immediately stating the action and object. No wasted words, front-loaded, appropriately concise 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?
For a mutation tool with no output schema, description should disclose critical behavior like whether the existing emoji list is replaced or merged, and any prerequisites (e.g., ownership of sticker set). The one-line description leaves these gaps, relying entirely on annotations for safety 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?
With 0% schema description coverage, the description must carry parameter meaning. It names 'list of emoji' and 'sticker' but does not explain format, constraints, or how the emoji_list should be constructed. It adds little beyond the parameter 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 uses a specific verb 'Change' and names the resource 'list of emoji associated with a sticker'. It clearly distinguishes from sibling tools like set_sticker_keywords or set_sticker_mask_position by focusing on emoji_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this when you want to modify the emoji list of a sticker. However, it offers no explicit alternatives, exclusions, or when-not guidance. The context is clear but not differentiated from other sticker setters.
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 it's a non-read-only, non-destructive, idempotent operation. The description adds no additional behavior context, such as permissions required, scoping (e.g., whether forum topics are excluded), or effects on the chat's pinned message list. 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 single, front-loaded sentence with no wasted words. It states the core action directly and is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter, no output schema, and good annotations, the description is minimally viable but lacks context about when to use it versus similar sibling tools and any limitations. The 'chat' scope could be ambiguous given the existence of forum-topic-specific unpin-all 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 schema covers 100% of the parameter descriptions (chat_id is 'Chat ID or @username'). The description adds no parameter-level information, so it earns the baseline score of 3.
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 ('Unpin') and resource ('all messages in a chat'), clearly distinguishing it from siblings like 'unpin_chat_message' (single message) and 'unpin_all_forum_topic_messages' (forum topic scope). The noun 'chat' matches 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 vs alternatives such as 'unpin_chat_message' or 'unpin_all_forum_topic_messages'. The description simply states the action without context, 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe read. The description adds no behavioral traits beyond that, such as error handling or return format. With annotations covering the safety profile, a 3 is appropriate as the description adds no additional 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. Every word earns its place with no redundancy or fluff. This is an ideal level 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?
Given the tool's low complexity (two parameters, no output schema) and rich annotations (readOnlyHint, idempotentHint), the description is sufficiently complete for an agent to select and invoke it. It could be enhanced by mentioning the return type (ChatMember), but the core purpose is clear.
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 100%, with both chat_id and user_id documented in the input schema. The description adds no parameter semantics beyond what the schema provides. Baseline 3 is correct since schema does the heavy lifting.
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 'Get information about a member in a chat' clearly states the verb (get) and resource (member in a chat), and it distinguishes from sibling tools like get_chat_member_count or get_chat_administrators. However, it is somewhat generic and doesn't specify what 'information' includes, keeping it from a full 5.
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 vs alternatives. It doesn't mention that it's for a single member, contrast with get_chat_administrators, or any exclusions. A single-sentence description with no usage context earns a 2.
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 read-only, idempotent, non-destructive behavior. The description adds only a version marker (v9.3), providing minimal extra behavioral context beyond what annotations already state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence that immediately conveys the purpose. 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 read-only getter with one well-documented parameter and strong annotations, the description is minimally sufficient. It doesn't explain return format or edge cases, but the simplicity and annotation coverage make it reasonably complete.
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 100%, with user_id documented as 'User ID'. The description doesn't add further meaning about the parameter, so it stays at the baseline for high 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 the tool fetches gifts received by a user, using a specific verb and resource. It doesn't explicitly distinguish from sibling tools like get_business_account_gifts, but the name and phrasing make the target 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 is provided on when to use this tool versus alternatives, or any prerequisites or context. The description only states what it does, not 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.
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 clear. The description adds no behavioral context beyond what annotations provide, such as pagination or return format, but 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 single, front-loaded sentence that conveys the core purpose without wasted words. The version tag is a minor addition but not unnecessary.
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 getter with good annotations, the description is minimally sufficient. It lacks explicit mention of pagination or output structure, but the schema's limit/offset parameters and the tool's name provide some context. It does not fully leverage the opportunity to clarify behavior beyond the schema.
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 parameter semantics. It only implies user_id through 'user's profile' but does not clarify limit, offset, or their roles, leaving the agent to infer from names and schema 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 clearly states the tool gets a user's profile audio tracks, using a specific verb and resource. The resource 'audio tracks' distinguishes it from the sibling 'get_user_profile_photos'.
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. The description does not mention that for photos one should use the sibling tool, nor any other exclusions or preferences.
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 that this is a non-read-only, non-destructive operation. The description adds the behavioral detail of supporting HTML/Markdown/MarkdownV2 formatting, which is useful context, but it omits broader behavioral aspects like permission requirements or potential side effects. This is acceptable given the annotations, but it does not go far 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 two short, front-loaded sentences with no filler or redundant phrases. Every word contributes to understanding the tool's core purpose and formatting capability.
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 13 parameters and no output schema, a one-sentence description is minimal but sufficient for basic use (sending text to a chat). It does not explain optional parameters or return behavior, but the schema partially covers some properties. This is a minimum-viable description 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 only 54%, so the description should compensate for undocumented parameters. It only restates that a chat is the target and that formatting modes are HTML/Markdown/MarkdownV2, which duplicates the parse_mode enum. It does not clarify optional parameters like reply_markup, entities, or link_preview_options, nor does it add 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 begins with the specific verb 'Send' and clearly identifies the resource as 'a text message to a chat,' which distinguishes it from sibling tools like send_photo or send_document. The mention of formatting modes further clarifies its intended scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/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 send_message versus alternatives such as send_photo, edit_message_text, or send_message_draft. It does not state exclusions or explicitly name alternative tools for other message types or actions.
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, destructiveHint=false, and idempotentHint=false, covering the safety profile. The description adds the key format requirement (.OGG/OPUS) beyond the schema, but does not disclose other behavioral traits such as error handling, size limits, or response behavior. 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?
A single sentence that is perfectly front-loaded and contains no wasted words. The format detail is packed efficiently into the sentence, earning its place by adding critical semantic 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?
This is a complex tool with 14 parameters, no output schema, and many siblings. The description covers only the core purpose and format, omitting return value, behavioral notes, and context for the many undocumented parameters. The minimal description is inadequate for this complexity level.
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 exactly 50%, with 7 of 14 parameters undocumented (duration, effect_id, protect_content, message_thread_id, allow_paid_broadcast, disable_notification, business_connection_id). The description adds meaningful format context for the voice parameter, but does not compensate for the half of the parameters lacking 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 uses a specific verb+resource ('Send a voice message') and adds the distinctive format constraint (.OGG encoded with OPUS), which clearly differentiates it from sibling tools like send_audio and send_video_note. This is a precise, unambiguous statement of purpose.
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_audio, send_video_note, or send_document. The description implies usage for voice messages but offers no exclusions, prerequisites, or decision context, which is a significant gap given the large set of send_* siblings.
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 write operation (readOnlyHint=false), non-destructive, and idempotent. The description adds no behavioral context beyond the action itself, such as the need for a previously established business connection or any 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, short sentence that is front-loaded with the action and resource. It contains no redundant or unnecessary information.
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, the description is minimally adequate, but it omits key context such as the requirement for a valid business_connection_id and the absence of an output schema means return behavior is not described. Overall, it covers the basic function but leaves important operational details to the schema.
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 mentions 'bio' without clarifying the format or purpose. The 'business_connection_id' parameter is not explained at all, leaving the agent to infer its meaning from the parameter name 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 a specific action ('Set') and a specific resource ('the bio of a business account'), distinguishing it from sibling tools like set_business_account_name and set_business_account_username.
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 saying exactly what it does, but it does not explicitly state when to use this tool over alternatives or provide any exclusions or prerequisites such as requiring a business connection.
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 provides no behavioral details beyond the annotations, which already indicate a non-destructive, idempotent write. It does not disclose any potential side effects, permission requirements, or behavior when keywords are omitted.
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 sentence with no filler, directly stating the action. It is front-loaded with the verb and resource.
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 no output schema and no parameter descriptions, the description offers minimal context. It does not explain what the tool returns, prerequisites, or the behavior when keywords are absent, leaving gaps for a mutation 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 schema has 0% description coverage, so the description must compensate. It identifies that 'sticker' refers to the target sticker and 'keywords' to the new search keywords, but it does not explain formats, replacement vs. appending behavior, or the effect of omitting the optional keywords parameter.
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 changes search keywords for a sticker, using a specific verb and resource. It distinguishes from sibling tools like set_sticker_emoji_list and set_sticker_mask_position which modify other sticker attributes.
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 need to modify a sticker's search keywords, but it offers no explicit guidance on when to use it over alternatives or any contextual prerequisites. No alternatives or exclusions 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 write operation (readOnlyHint=false), idempotent, and non-destructive. The description adds little beyond stating the move action; it does not disclose side effects like shifting other stickers or validation behavior. However, it does not contradict annotations, so it meets the 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?
The description is a single, clear sentence with no redundant information. It effectively communicates the core action in minimal words.
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 (2 required parameters, no output schema) and the annotations covering safety profile, the description is minimally adequate but lacks context about return values, errors, or prerequisites like the sticker needing to be in the set. It does not fully leverage the opportunity to clarify usage among many sibling tools.
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 0% description coverage, and the description only mentions 'sticker' and 'position' without explaining their formats or semantics. For example, 'sticker' could be a file ID or a sticker object, and 'position' is implied to be 0-based via the schema minimum. The description does not 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the imperative 'Move' to specify a clear action on a sticker, with scope 'to a specific position in the set.' This distinguishes it from siblings like add/delete/replace, which have different operations. It clearly conveys the reordering purpose.
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 is provided for when to use this tool versus alternatives. While it's implicitly for reordering existing stickers, the description does not mention exclusions, prerequisites (e.g., sticker existence), or alternatives such as set_sticker_mask_position. This is a clear gap.
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-destructive, idempotent operation, but the description adds no behavioral context such as permission requirements, visibility effects, or side effects. It merely restates the action implied by the tool name.
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-sentence description is extremely concise and front-loaded, with no wasted words. It states the essential action 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 tool with one parameter and no output schema, the description is adequate. It clearly states what it does; could mention prerequisites like forum-enabled chats, but that is implied by the tool name and sibling context.
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?
Single parameter chat_id is fully described in the schema as 'Chat ID or @username', providing 100% coverage. The description adds no additional parameter details, so baseline 3 applies.
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 'Unhide' and resource 'the General topic', clearly distinguishing it from siblings like hide_general_forum_topic and close_general_forum_topic. The action is 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 guidance on when to use this tool vs alternatives. It does not mention prerequisites such as forums being enabled, or when to prefer unhide over reopen, leaving the agent to infer usage 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?
Annotations already declare idempotentHint=true, destructiveHint=false, openWorldHint=true, and readOnlyHint=false, which cover the safety profile. The description adds the organizational context but no further behavioral traits like effects, reversibility, or permissions. 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 single, concise sentence that immediately states the action and scope. There is no redundant wording or unnecessary detail, making it efficient and easy to parse.
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 two-parameter mutation with no output schema, the description is minimally adequate but leaves clear gaps. The semantics of custom_description are unexplained, and there is no mention of response behavior or when to use this over related tools. Annotations mitigate some concerns but not all.
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 describes chat_id ('Chat ID or @username') but custom_description only has a maxLength constraint without meaning. The tool description adds no explanation of parameters, so the agent is left without context for custom_description. Schema coverage is only 50%, and the description fails to compensate.
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 ('Verify'), the resource ('a chat'), and the scope ('on behalf of the bot's organization'). It distinguishes from sibling tools like verify_user by specifying the resource type, 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 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 verify_user or remove_chat_verification. It lacks any prerequisites, exclusions, or contextual cues beyond the basic action, so the agent cannot infer appropriate usage situations.
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 key behavioral constraint: the link is for a channel chat. Annotations (readOnlyHint=false, destructiveHint=false) already convey the write, non-destructive nature. However, it does not disclose permission requirements, the fact that the link is associated with a subscription, or side effects beyond creation, 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 sentence, 8 words, with a clear verb-first structure. It is perfectly concise and front-loaded with no redundant information.
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?
There is no output schema, so the description should explain return values or additional context, but it does not. It also fails to mention required permissions, the meaning of subscription parameters, or how this interacts with sibling tools, making it incomplete for a 4-parameter mutation 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?
Schema description coverage is only 25% (only chat_id is described). The description does not explain subscription_price or subscription_period (e.g., currency, units, allowed values). It adds no meaningful parameter semantics beyond the parameter names, failing 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 uses a specific verb 'Create' and identifies the resource 'subscription invite link' for 'a channel chat'. This clearly distinguishes it from sibling tools like create_chat_invite_link (regular invite link) and edit_chat_subscription_invite_link (editing an existing link).
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 creating paid subscription links in channels but lacks explicit guidance on when to use this tool versus create_chat_invite_link or any prerequisites such as admin rights. There is no mention of alternatives or exclusions, so it provides only implied 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 is consistent with annotations (readOnlyHint=false indicates a write operation). It adds the version requirement and the chat type scope, but does not describe side effects, permissions, or return behavior. Given annotations already cover the mutation safety profile, the description adds only marginal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-structured sentence with no redundant words. It front-loads the action and includes a version qualifier. It is appropriately concise for the tool's 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?
For a create operation with 4 parameters and no output schema, the description is too sparse. It does not explain the required parameters 'name' and 'chat_id' in the context of this tool, nor does it mention what the tool returns. The low parameter coverage and lack of return value description leave gaps that the description does not fill.
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 only 25% (only chat_id has a description). The description does not mention any of the parameters, and it does not compensate for the missing documentation of 'name', 'icon_color', or 'icon_custom_emoji_id'. Minimal inference can be made from the phrase 'topic' but it is not explicit enough to guide parameter usage.
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 'Create' and identifies the resource 'a topic' and context 'in a forum supergroup or private chat', clearly distinguishing it from sibling tools like edit_forum_topic and delete_forum_topic. The version constraint adds clarity. This is a clear purpose statement.
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 by specifying the context (forum supergroup or private chat) and the version requirement (v9.4+), but does not explicitly discuss alternatives or exclusions. There is no guidance on when to choose this over other topic-related tools, so it relies on the reader's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, and the description's 'Delete' is consistent. However, the description does not disclose a critical behavioral nuance: this tool only removes the chat's association with the sticker set, not the sticker set itself (unlike the sibling 'delete_sticker_set'). This omission could mislead an agent into thinking the actual sticker set is deleted. The description adds only the scope 'from a supergroup' 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: 'Delete the sticker set from a supergroup.' It contains no filler and conveys the essential information 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?
Given the tool's simplicity (one parameter, no output schema) and annotations providing destructive hint, the description is minimally adequate. However, it lacks crucial context about side effects (the sticker set itself remains) and prerequisites (admin rights), which is important for a destructive operation. The presence of a similarly named sibling raises the need for clarification, which is missing.
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 100% description coverage for the single 'chat_id' parameter, documenting it as 'Chat ID or @username'. The description adds no parameter-specific information, but the schema already handles it fully. Baseline of 3 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 states a specific action: 'Delete the sticker set from a supergroup.' The verb 'delete' and resource 'sticker set' are explicit, and the scope 'from a supergroup' distinguishes it from the sibling 'delete_sticker_set' which deletes a sticker set entirely. This is a specific verb+resource+scope combination.
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 supergroups but provides no explicit guidance on when to use this tool versus alternatives. It does not mention that 'delete_sticker_set' is for removing a sticker set globally or that 'set_chat_sticker_set' is the counterpart for setting it. The context is clear enough for a supergroup deletion, but no exclusions or alternatives are named.
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 read-only, idempotent, non-destructive. Description adds only a version tag (v9.3) and the chat scope, which is purpose rather than behavior. No additional behavioral context like pagination, permissions, or return limitations 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?
Single sentence, no waste. The parenthetical version is extraneous but not overly verbose. Perfectly concise for a simple 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?
Tool is simple with one well-documented parameter and full annotations. However, no output schema exists, and the description does not clarify the return structure or any pagination/limits. This leaves some ambiguity, but it is a basic getter.
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 covers 100% of the parameter with 'Chat ID or @username'. Description adds no additional meaning beyond the schema, so baseline 3 applies.
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 'Get' and resource 'gifts received by a chat' which clearly distinguishes it from siblings like get_user_gifts and get_available_gifts. The scope (chat vs. user) is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs. alternatives. The resource scope is clear, but there are no exclusions or named alternative tools. Usage is implied by the resource 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, idempotentHint, and destructiveHint, covering safety profile. The description adds 'current' indicating a snapshot, but does not disclose details about default scope, language behavior, or response format. Annotation coverage lowers the bar, yet the description adds minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of six words. Every word carries meaning, and there is no fluff or repetition.
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?
Without an output schema, the description only says 'command list,' which gives a vague hint. It does not explain the two parameters, the return structure, or potential empty results. For a simple getter, this may be passable, but the lack of parameter clarity and output details makes it incomplete.
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 describes two parameters (scope, language_code) with 0% coverage, and the description completely omits any mention of them. The agent has no guidance on what scope means (likely a BotCommandScope object) or how language_code affects output. This is a significant gap that the description fails to compensate for.
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') and the target ('the bot's current command list'). It is specific enough to distinguish from sibling tools like set_my_commands (which modifies commands) and get_my_name (which retrieves a different resource).
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 for retrieving the current command list, which gives clear usage context. However, it does not explicitly mention when not to use it or point to alternatives like set_my_commands. Given the simple read-only nature, the implied usage is clear but no exclusions are stated.
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 covered. The description adds no additional behavioral context, such as how statistics are computed, whether the result is deterministic, or what is included in the summary.
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 unnecessary words. It efficiently conveys the tool's purpose in a clear, direct manner.
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 with only two optional parameters and strong annotations, but there is no output schema. The description does not specify what 'summary statistics' are returned (e.g., counts, averages, distributions), leaving a gap in expected behavior for the agent.
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 complete descriptions for both parameters ('since' and 'requester') with 100% coverage, so the baseline is 3. The description does not mention or add any further meaning to these parameters, leaving the schema to carry the semantic load.
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 'Get summary statistics from the TRAIL content log', which is a specific verb ('get') and resource ('summary statistics' from 'TRAIL content log'). This clearly distinguishes it from siblings like 'get_trail', which presumably returns raw entries.
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 word 'summary statistics' — indicating an aggregate view rather than raw log entries from sibling 'get_trail'. However, there is no explicit guidance on when to use it versus alternatives, nor 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the 'long polling' behavior, which is useful, but it does not disclose that the call waits for updates, returns an array of Update objects, or that webhook setup would conflict with polling.
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 of five words. It is immediately clear 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.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain what the function returns, but it does not. It also omits important context like long-polling timeout behavior and the exclusivity with webhooks. The tool is simple, but the description is too sparse to fully inform the 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?
The schema has four parameters (limit, offset, timeout, allowed_updates) with 0% description coverage. The description provides no explanation of these parameters. While the names are somewhat self-explanatory in the context of polling, the description does not add any 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 tool's function: 'Receive incoming updates via long polling.' It uses a specific verb ('receive') and resource ('incoming updates'), and the method ('long polling') distinguishes it from webhook-related alternatives like set_webhook.
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 'via long polling' implies this is the polling method for receiving updates, but it does not explicitly explain when to prefer it over webhooks or mention that webhook and polling are mutually exclusive. No alternatives are named.
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 declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. However, the description adds no additional behavioral context such as irreversibility, permission requirements, or impact on other API calls. It simply restates the action already implied by the tool name, providing no 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence: 'Bot leaves a group, supergroup, or channel.' It is direct and contains no filler, exemplifying perfect conciseness where every word 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 simplicity (one parameter, no output schema) and the annotations providing the destructive hint, the description is minimally viable. However, it omits useful context such as the precondition that the bot must be a member of the chat, and what response to expect (e.g., success booleans). It could be enhanced with a note about post-leave behavior.
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 100%: the only parameter, chat_id, is fully described as 'Chat ID or @username'. The tool description adds no parameter-specific detail, but the schema already carries the semantic load, so the baseline score of 3 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 uses a specific verb 'leaves' and clearly identifies the resource (group, supergroup, or channel). It is distinct from sibling tools that modify or manage chats rather than exit them, 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 usage when the bot needs to exit a chat, but it does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention scenario exclusions or prerequisites. The intent is somewhat self-evident from the name, but the description lacks explicit 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?
Annotations already indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is known. The description adds only the version note '(v9.6)' and does not disclose additional behavioral traits such as token invalidation or permission requirements, but 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 single, front-loaded sentence with no redundant words. It communicates the essential action and resource 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 tool is simple with one parameter and clear annotations, but the description omits potentially useful context such as the meaning of 'user_id' in this context and the effect of replacement on the existing token. It is minimally complete but could be improved.
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 description covers the only parameter 'user_id' with a basic 'User ID' description, providing 100% coverage. The tool description does not add extra meaning or clarify whether this ID refers to the bot or its owner, but the schema is sufficient.
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 verb and resource: 'Replace the token of a managed bot'. This distinguishes it from the sibling 'get_managed_bot_token', which retrieves rather than modifies the token.
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 'get_managed_bot_token'. The description does not mention prerequisites, effects, or typical use cases, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a key behavioral trait—content appears progressively—which adds value beyond the annotations. However, it does not explain what 'draft' means (e.g., whether the message is temporary or will be replaced), nor other implications like editing or cancellation. Given the annotations only hint at read/write safety, this level of transparency is moderate.
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 succinct sentences with the core action front-loaded in the first sentence. It contains no extraneous words or repetitive content, making it an excellent example of 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?
Given the tool's 12 parameters and lack of an output schema, this brief description is insufficiently complete. It omits return value information, usage prerequisites, and any alternative tool mentions, leaving the agent with only the streaming behavior as extra 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 description provides no additional meaning for the parameters beyond the schema. With schema description coverage at 50%, the description does not compensate for undocumented parameters such as entities or effect_id, leaving semantic gaps that could confuse 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 uses the specific verb 'Send' with the resource 'draft message' and the qualifier 'streaming', clearly distinguishing it from the sibling send_message. The added phrase 'Content appears progressively as it's being generated' reinforces its unique behavior, leaving no ambiguity about its primary 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 usage when streaming or progressive content is desired, but it does not explicitly state when to use this tool versus alternatives like send_message. No exclusions or alternative tool names are provided, so the agent must infer the context from the 'streaming' qualifier.
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 dual 'set or remove' behavior beyond the tool name, but annotations already provide idempotency and non-read-only hints. It does not disclose how removal is triggered (e.g., omitting tag) or any side effects. With annotations covering some safety traits, 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 a single, front-loaded sentence with no filler. Every word contributes to conveying the core function and version, making it appropriately concise.
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 a simple 3-parameter schema and annotations, but the description omits how removal is performed (e.g., whether omitting tag removes it or an empty string is required). No output schema exists, so the description should clarify this, but it does not. Still, the tool is simple enough that this is a moderate gap.
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 descriptions cover 67% of parameters (chat_id and user_id), and the description does not add semantic details for 'tag'—it only mentions the word. Since schema coverage is high, the baseline is 3, and the description offers no extra meaning to compensate for the undocumented tag parameter.
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 ('Set or remove') and the resource ('a tag for a chat member'), which is specific and distinguishes it from sibling tools like set_chat_title or restrict_chat_member. It is not a tautology and provides a precise verb+object structure.
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 vs alternatives, nor any exclusions or prerequisites. It simply restates the function without contextual cues, leaving the agent to infer usage solely from the name and purpose.
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 the operation is not read-only, not destructive, and idempotent. The description adds minimal behavioral context beyond scope ('default permissions for all members' vs. individual permissions). It does not disclose additional effects such as how existing member permissions are affected or whether changes are reversible, but given annotations cover the safety profile, a score of 3 is reasonable.
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 without redundancy or filler. It is appropriately concise for what it does state.
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 having only 3 parameters and no output schema, the description is too minimal. It does not explain the 'permissions' object structure, provide usage guidance relative to sibling tools, or describe return values/behavior. An agent would struggle to correctly invoke the tool without additional 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?
Schema description coverage is only 33% (only 'chat_id' has a description). The tool description does not enrich the meaning of the 'permissions' parameter (which expects a permission object) or 'use_independent_chat_permissions' (likely a boolean toggle). Since schema coverage is low, the description should compensate but fails to explain parameter structure or behavior.
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 ('Set default permissions') and the target scope ('all members in a group/supergroup'). This distinguishes it from sibling tools like 'set_chat_title' (which sets a title) and 'restrict_chat_member' (which restricts individual members).
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 specifying 'default permissions for all members,' which suggests it is for group-wide defaults rather than per-member restrictions. However, it does not explicitly state when to use this tool versus alternatives like 'restrict_chat_member' or 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.
Behavior3/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), idempotent, and non-destructive. The description adds the fact that emoji or custom emoji are supported, but it does not disclose behaviors like whether setting a reaction replaces existing ones or that an empty reaction removes it. This is a modest addition 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 exactly two short sentences, front-loaded with the action, and contains no redundant words. It is appropriately concise for the tool's 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 4 parameters including an optional reaction and is_big flag, plus practical nuances (e.g., removing a reaction by omitting it), the description is too sparse to be complete. It omits critical usage context and leaves the agent to guess important behaviors, making it adequate but far from comprehensive.
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 coverage is low at 25% (only chat_id has a description). The description provides a brief note about the reaction parameter ('Use emoji or custom emoji') but does not explain is_big, message_id, or the optionality of reaction. This insufficiently compensates for the coverage gap, leaving several parameters without meaningful 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 clearly states the tool's purpose with a specific verb ('Set') and resource ('a reaction on a message'), making it easy to distinguish from sibling tools like send_message or edit_message_text. The additional detail about using emoji or custom emoji reinforces the purpose without ambiguity.
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 used when you want to react to a message, but it provides no explicit guidance on when to use it versus alternatives, nor any exclusions or prerequisites. The use case is clear but not elaborated.
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 non-read-only, idempotent, non-destructive operation. The description adds the context that the short description is shown on the profile page, but it does not disclose behaviors such as whether the operation replaces an existing description or how language codes are handled. Given annotation coverage, the description provides modest extra value.
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, well-structured sentence with no unnecessary words. It front-loads the main verb and resource, making it immediately understandable.
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 parameters and no output schema, the description is too minimal to be fully actionable. It does not clarify the role of language_code or differentiate from similar tools like set_my_description. While the core operation is obvious, critical usage details are missing.
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 explain parameters. It mentions only 'short description' which maps to the short_description parameter, but completely ignores the language_code parameter and its optional nature. This leaves a significant gap in understanding the full input contract.
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 'set' and the resource 'bot's short description', with the additional context 'shown on profile page'. This distinguishes it from sibling tools like set_my_description and set_my_name, which address different profile attributes.
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 by naming the purpose, but it does not explicitly state when to prefer this over set_my_description or how the optional language_code parameter is meant to be used. No alternatives or exclusions are mentioned, so guidance is only implicit.
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 idempotentHint=true and destructiveHint=false. The description adds the qualifier 'previously banned', implying this only applies to banned chats, but does not elaborate on side effects, permissions, or error 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, focused sentence with no redundant wording. It is front-loaded with the verb and object.
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 two-parameter tool with annotations providing safety info, the description is minimally adequate. However, it lacks details on preconditions (e.g., must be banned), return values, or behavior when the chat is not banned, making it incomplete for an agent fully reliant on it.
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 50%: chat_id has a description, but sender_chat_id is undefined. The description does not explain sender_chat_id explicitly, though 'previously banned channel chat' hints at its role. This partially compensates but leaves 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 clearly states the action ('Unban') and the resource ('previously banned channel chat'). It distinguishes from related tools like unban_chat_member by focusing on sender 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, nor any prerequisites or exclusions. The description merely states what it does without contextual 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?
Annotations already indicate this is a non-read, non-destructive, idempotent write operation. The description adds that the upload is a preparatory step, but it doesn't disclose return values, auth requirements, or file constraints. It provides minimal added 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?
A single, concise sentence that directly states the action and its purpose. No wasted words or redundancy.
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 three required parameters and no output schema, but the description does not explain the return value (likely a file_id), the meaning of user_id, or required file format constraints. It is underspecified for an agent to use effectively without additional assumptions.
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 only 33% (only the 'sticker' parameter is described). The description offers no parameter guidance whatsoever. The purpose of 'user_id' in this context is ambiguous, and the description does not clarify how parameters relate to the stated 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 the action: 'Upload a sticker file to Telegram', which is a specific verb and resource. It further distinguishes itself by noting 'for later use in createNewStickerSet', separating it from other sticker-related tools like send_sticker or create_new_sticker_set.
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 ties the tool to a specific use case: preparing files for createNewStickerSet. It gives clear context for when to use it, but it lacks explicit alternatives or exclusions, such as the ability to pass a URL directly instead of uploading.
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 this is not read-only, not idempotent, and not destructive. The description adds a crucial behavioral constraint: the tool must be answered within 10 seconds. This is a rate/performance limit that goes beyond the annotation fields and is useful for the agent's decision-making.
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, using just two short sentences. Both sentences carry essential information: the purpose and the time constraint. There is no unnecessary fluff, so it scores well on conciseness, though the lack of detail limits its overall utility.
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 no output schema, so the description should explain what the response looks like or what the tool returns. It also does not describe the meaning of the parameters or how ok/error_message relate to the pre-checkout query. This leaves the description incomplete for a tool with three parameters and no output schema.
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 agent cannot infer what pre_checkout_query_id, ok, or error_message mean from the description alone, leaving a critical gap in understanding how to invoke the tool correctly.
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 'respond' with the resource 'pre-checkout queries', clearly distinguishing this tool from sibling tools like answer_shipping_query, answer_inline_query, and answer_callback_query. It names the exact type of query it handles.
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 by specifying it handles pre-checkout queries, which implies it is for pre-checkout rather than other query types. However, it does not explicitly state when not to use it or mention alternative tools, so it stops short of full 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?
The description explicitly notes that it sends a message on behalf of the user, a key behavioral side effect not fully covered by the annotations (which only indicate non-read-only and non-destructive). This adds useful context beyond the structured fields, though it could mention that it consumes the web_app_query_id or returns a response.
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 with no wasted words, front-loading the action. It is appropriately concise, though it sacrifices some helpful detail 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?
The tool has no output schema and complex parameter semantics (result is an untyped object). The description does not explain return values, prerequisites, or the expected web app query flow. It provides only a basic purpose, leaving significant gaps 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.
Parameters2/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 for parameter clarity. It references 'result' and 'interaction' but does not explain the web_app_query_id parameter or the expected structure of the 'result' object. The schema provides only raw property names, and the description adds minimal meaning beyond that.
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 ('Set the result of an interaction') and the resource ('Web App'), with an additional effect ('send a message on behalf of the user'). This distinguishes it from sibling 'answer_*' tools like answer_callback_query or answer_inline_query, which handle different query types.
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 ('interaction with a Web App') but does not explicitly state when to use it versus alternatives, nor does it describe exclusions or prerequisites. The purpose is evident, but no direct comparison to sibling tools is 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 that in supergroups/channels the ban is permanent until unbanned, adding context beyond the destructiveHint annotation. It doesn't cover permission requirements or message revocation behavior, but annotations already signal destructiveness.
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 action, no redundant or filler content.
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 basic purpose and one behavioral consequence, but lacks essential details about the until_date and revoke_messages parameters and the required admin permissions. Given the absence of an output schema and moderate parameter count, it's adequate but incomplete.
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 semantics. The schema describes chat_id and user_id, but until_date and revoke_messages are undocumented in both schema and description, leaving ambiguity about temporary bans and message revocation.
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 'Ban a user from a chat' with a specific verb and resource, and adds a concrete behavioral nuance about supergroups/channels. This distinguishes it from related sibling tools like restrict_chat_member or unban_chat_member.
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. The description doesn't mention that unban_chat_member reverses it or that restrict_chat_member could be used for temporary restrictions. Only a context note about supergroups is provided, not explicit usage directions.
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, readOnlyHint=false, and idempotentHint=false. The description adds the specific effect (restricting sending messages) but does not disclose additional behavioral context such as reversibility, side effects, or required permissions. 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?
A single concise sentence that conveys the core action without any redundant words or filler. It is appropriately front-loaded and easy to parse.
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, but the description omits important context such as the meaning of sender_chat_id, return value, and error cases. The presence of annotations helps, but the lack of a full parameter description and no output schema leave gaps in 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?
Schema description coverage is only 50%: chat_id has a description ('Chat ID or @username') but sender_chat_id has none. The tool description provides no additional parameter semantics, leaving the purpose of sender_chat_id unexplained and not compensating 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 uses a specific verb 'ban' and clearly identifies the resource ('channel chat') and context ('in a supergroup'). It distinguishes itself from sibling tools like 'ban_chat_member' (which bans users) and 'unban_chat_sender_chat' (the inverse 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 channel chats in supergroups but offers no explicit guidance on when to use this tool versus alternatives such as 'ban_chat_member' or when to use the inverse 'unban_chat_sender_chat'. No exclusions or alternative conditions 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?
The annotations already declare the destructiveHint=true, so the description does not need to repeat that. However, the description adds no extra behavioral context such as irreversibility, permission requirements, or side effects. It is consistent with annotations but provides no additional transparency value.
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 directly states the tool's purpose with no filler or redundant content. It is extremely concise and well-structured, earning a perfect score for minimalism.
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, no output schema) and the presence of annotations, the description is mostly sufficient. It successfully names the action and resource, but lacks any additional context about when deletion is appropriate or any side effects. However, for such a simple tool, the description is nearly complete.
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 'chat_id' is fully described in the input schema with 'Chat ID or @username', achieving 100% schema description coverage. The tool description adds no information about the parameter, so it neither helps nor hurts beyond what the schema already provides.
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 ('a chat photo'), making it unambiguous what the tool does. It also distinguishes itself from sibling tools like 'set_chat_photo' and 'delete_chat_sticker_set' by explicitly naming the photo 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 provides no guidance on when to use this tool versus alternative tools, nor does it mention any prerequisites or situations where it should not be used. The only hint comes from the tool name itself, which is insufficient for scenario-based decision-making.
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=false, idempotentHint=true, and destructiveHint=false, covering the basic safety profile. The description adds the 'media message' constraint, which is useful context. It doesn't disclose permission requirements or behavior on invalid messages, but given annotation coverage, it's adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no superfluous words. It fully earns its place by stating exactly what the tool does.
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 8 parameters and no output schema, the description is brief but sufficient to understand the core function. It doesn't cover important invocation details like parameter combinations (chat_id+message_id vs inline_message_id) or prerequisites, but the schema provides some guidance. Overall it's adequate with 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 schema descriptions cover 63% of parameters (5 of 8), but the description adds no information about the remaining parameters (caption, inline_message_id, show_caption_above_media). While the name hints at the caption parameter, the description fails to clarify the alternative identification via message_id vs inline_message_id, leaving gaps 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 uses a specific verb ('Edit') and names the exact resource ('caption of a media message'), clearly distinguishing it from sibling edit tools like edit_message_text or edit_message_media. It leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying 'media message', indicating it's intended for editing captions of media messages rather than text or other message types. However, it doesn't explicitly mention when to use it over alternatives like edit_message_text or edit_message_reply_markup, nor 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 and destructiveHint=false, and the description is consistent. However, it adds no additional behavioral context beyond a simple read, such as rate limits, authorization requirements, or that the balance may change due to external transactions. The description adds minimal context 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 one short, direct sentence with no wasted words. It front-loads the action and resource, making it easy to parse quickly.
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?
While the tool is simple and annotations cover safety, the description lacks argument guidance (business_connection_id) and return-value details. Given there is no output schema, this leaves the agent without a complete picture of how to invoke the tool or interpret results. 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 one parameter (business_connection_id) with 0% description coverage, and the description does not explain what this ID is or how to acquire it. Since schema coverage is low, the description should compensate by describing the parameter, but it does not, leaving the agent to infer meaning from the parameter name 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 uses a specific verb ('Get') and resource ('Telegram Stars balance of a business account'), clearly distinguishing it from sibling tools like get_my_star_balance or get_business_account_gifts. It states exactly what the tool 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 phrase 'of a business account' implies this tool is for business account balances rather than personal (get_my_star_balance), but no explicit when-to-use or alternative references are provided. It relies on the user to infer context 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, so the agent knows this is a safe read operation. The description adds no additional behavioral context beyond stating it returns a list, but it is consistent with the annotations. No extra details about permissions, pagination, or error handling are provided, but the annotations carry the safety 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, grammatically correct sentence with no filler words. It is front-loaded with the verb and resource, and every word contributes to meaning. Perfectly concise for a simple 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 tool's simplicity (one parameter, no output schema, strong annotations), the description is largely sufficient. It clearly states the return intent ('list of administrators') and is safe to invoke. It could be more complete if it mentioned that this works for any chat (public, group, supergroup) or explicitly noted that no admin rights are needed, but these are implied by the domain context.
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 covers the only parameter (chat_id) with a description 'Chat ID or @username' (100% coverage). The tool description adds no further semantic detail about the parameter format or constraints, so the baseline of 3 applies.
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') and resource ('list of administrators in a chat'), clearly distinguishing it from sibling tools like get_chat_member (single member) or get_chat_member_count. The phrase 'list of administrators' is unambiguous and directly matches 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?
The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions (e.g., 'use get_chat_member for a single admin') or prerequisites (e.g., 'requires admin rights'). The usage context is only implied by the name and resource.
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 description is not required to restate safety. However, it adds no additional behavioral context such as error handling, chat type limitations, or return value specifics, failing to add value beyond what annotations already 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 a single, clear sentence with no wasted words, effectively front-loading 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?
This is a simple read-only tool with one well-documented parameter and strong annotations. The description fully conveys the purpose, and while the return format isn't explicitly stated, it is obvious from the name and description, making the description adequate for the tool's simplicity.
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 covers 100% of the single parameter (chat_id) with a description, and the tool description adds no extra parameter meaning. With high schema coverage, the baseline of 3 applies.
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 'Get the number of members in a chat' uses a specific verb and resource, clearly distinguishing it from sibling tools like get_chat_member which retrieves an individual member's details. It unambiguously states 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?
No explicit when-to-use or when-not-to-use guidance is provided, nor are alternatives mentioned. The usage context is implied by the name and description but not articulated, leaving the agent to infer when this tool is appropriate relative to similar chat-related 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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety. It adds the minor version context 'v9.6' but does not disclose any other behavioral traits like token sensitivity or authentication requirements. 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 single sentence, directly states the action, and includes a version qualifier without unnecessary words. It is optimally concise 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 tool's simplicity (one parameter, no output schema) and strong annotations, the description is largely sufficient. The phrase 'managed bot' is specific to the Telegram API and might benefit from a brief explanation, but the overall context is adequate for an agent familiar with the domain. The version note adds a useful completeness touch.
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 100% with the parameter 'user_id' described as 'User ID'. The description adds no additional parameter meaning beyond the schema. Since the schema already documents the parameter, the baseline of 3 applies.
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' and a clear resource 'token of a managed bot'. It clearly distinguishes from the sibling tool 'replace_managed_bot_token' by indicating a read operation rather than a replacement. The version 'v9.6' adds specific 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?
No usage guidance is provided. The description does not mention when to use this tool versus alternatives, such as 'replace_managed_bot_token'. There is no mention of prerequisites, typical scenarios, 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 convey read-only, idempotent, non-destructive behavior, and the description aligns without contradiction. However, it adds no extra behavioral context beyond language scoping—e.g., what happens if language_code is missing or unsupported, or whether it falls back to a default.
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 of eight words that states the tool's core function without any wasted words or redundancy. Perfectly sized for the simple operation.
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 getter with one optional parameter and no output schema, the description mostly suffices but omits the behavior when language_code is not provided (e.g., default language) and the exact format of the returned value. The rich annotations cover safety but not these functional details.
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 coverage is 0% and the description only says 'for a given language', which essentially restates the parameter name 'language_code' without adding format (e.g., ISO 639-1), allowed values, or default behavior. The sole parameter is optional, but the description does not clarify the implication of omitting it.
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 a specific verb ('get') and resource ('the bot's name') with a clear scope ('for a given language'), distinguishing it from siblings like get_my_description or set_my_name. The purpose is immediately understandable 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for a given language' implies the tool is used when a localized bot name is needed, but it does not explicitly state when to use it over alternatives or exclude scenarios (e.g., getting the default name when no language is specified). No alternative tools 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 mutating operation (readOnlyHint=false) and not destructive. The description adds format constraints but does not disclose other behavioral traits such as required permissions, file size limits, or side effects. 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 a single, concise sentence that conveys the core purpose without any wasted words. It is front-loaded and easy to parse, which is appropriate for the tool's simplicity.
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 has 18 parameters and no output schema, the description is minimal. It adequately covers the basic purpose and format, but it does not explain return values, typical use cases, or the role of many optional parameters. This is acceptable 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?
Schema description coverage is only 44%, and the description does not compensate by explaining any parameters. It does not even mention the key required parameters (chat_id, animation) beyond what is in the schema. It adds no parameter-level 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 tool sends an animation, with specific format constraints (GIF or H.264/MPEG-4 AVC video without sound). This distinguishes it from sibling tools like send_video (which typically sends video with sound) and send_photo.
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 specifying 'without sound', suggesting that send_video would be for videos with sound, but it does not explicitly provide when-to-use or alternative guidance. There is no explicit exclusion or reference to sibling 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 this is a write operation (readOnlyHint=false), idempotent, and non-destructive. The description adds no additional behavioral context beyond the action itself, such as permission requirements or side effects. It is consistent with annotations but does not enrich 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 concise sentence (8 words) that immediately conveys the tool's purpose. 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 mutation tool with two string parameters and no output schema, the description is adequate. It identifies the resource and the action. However, it could be slightly more explicit about the role of each parameter, but overall it is complete enough given the tool's simplicity.
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 must compensate. It implies that 'title' is the new title value and 'name' identifies the sticker set, but does not explicitly map the parameters or explain formats. This is minimal but sufficient for a simple two-parameter 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 ('Set') and the resource ('title of a sticker set'), making it easy to understand what the tool does. It is specific enough to distinguish from sibling tools like set_sticker_set_thumbnail or set_sticker_emoji_list, which target different properties.
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. There is no mention of prerequisites, context, or exclusions. Sibling tools for other sticker set modifications exist, but no comparison or selection criteria are given.
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, destructiveHint=false, and idempotentHint=true, so the agent knows it's a non-destructive write. The description adds the action semantics but doesn't disclose additional behavioral details such as failure modes or effects on balances beyond the transfer.
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 concise sentence, no redundancy, 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 simple two-parameter tool with good annotations, the description is adequate but lacks context about prerequisites (e.g., how to obtain business_connection_id) and expected response. It is not fully complete but acceptable for a simple transfer operation.
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 provides no descriptions (0% coverage), and the description does not explain the parameters. While the names business_connection_id and star_count are somewhat self-explanatory, the description does not clarify where to obtain the connection ID or any constraints 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 uses a specific verb 'transfer' and clearly identifies the resource (Telegram Stars), source (business account), and destination (bot), distinguishing it from sibling tools like get_business_account_star_balance or refund_star_payment.
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 need to move stars from a business account to the bot) but does not explicitly mention when to use it versus alternatives, nor does it state prerequisites like needing an active business connection.
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 (mutation), idempotentHint=true, and destructiveHint=false. The description adds the specific scope ('General' topic) but offers no further behavioral context such as whether admin rights are required or what happens when no messages are pinned. 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 single, front-loaded sentence: 'Unpin all messages in the 'General' topic.' Every word is meaningful and there is no fluff 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 one parameter and good annotations, the description is largely complete. It could hint at the requirement that the chat must have a General forum topic, but given the sibling tool family and the context, this is not a significant gap. No output schema exists, so no return-value explanation is needed.
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 100% for the single parameter (chat_id), with its own description. The tool description does not add any additional parameter details, so it relies on the schema. Baseline of 3 is appropriate given full 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 uses the specific verb 'Unpin' with the resource 'all messages in the 'General' topic,' clearly distinguishing it from siblings like unpin_all_forum_topic_messages (which targets a specific topic by ID) and unpin_all_chat_messages (all messages in the chat). It is concise 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 explicit guidance is provided on when to use this tool versus alternatives such as unpin_all_forum_topic_messages. The scope is implied by the name and description, but there is no statement of exclusions, prerequisites (e.g., chat must be a forum), or scenarios where another unpin tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation as non-read-only, non-destructive, and idempotent, and the description is consistent with these. It adds no additional context about permissions or side effects, but the annotation coverage lowers the bar.
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?
Five words, immediately clear, no wasted text.
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 mutation tool, the description is adequate but leaves the optional message_id semantics unexplained. It also doesn't distinguish from forum-topic unpin operations, but that may be outside scope.
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 already documents chat_id (Chat ID or @username), but message_id lacks any description and the tool description doesn't clarify its role or optionality. With 50% schema coverage, the description should compensate but doesn't.
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 clear verb ('Unpin') and resource ('a message in a chat'), directly distinguishing it from sibling tools like 'pin_chat_message' and 'unpin_all_chat_messages'.
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 or alternatives are mentioned, but the name and description imply it unpins a single message, as opposed to unpinning all messages, which is covered by sibling tools. This is sufficient but not 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 indicate idempotent and non-destructive behavior. The description adds no extra context about side effects, permissions, or failure conditions. It is accurate but does not go beyond the structured data.
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, clear sentence with no unnecessary words. It is well-structured 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?
The tool is simple with only 2 parameters and no output schema. However, the description lacks context about when this action is applicable (e.g., requiring admin rights, that the request must be pending) and its expected effect. Slightly incomplete for a mutation 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 input schema covers both parameters fully (100% coverage), including chat_id's format and user_id's type. The description does not add further parameter semantics, which is acceptable given the 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 uses a specific verb ('Approve') and resource ('chat join request'), clearly stating the tool's function. It also inherently distinguishes from the sibling 'decline_chat_join_request' 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by the description and name — to accept a user's request to join a chat. However, there is no explicit guidance on when to use this versus alternatives like decline_chat_join_request, or any preconditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey idempotency and non-destructiveness. The description adds the allowed media types but does not disclose operational constraints such as replacement behavior, permission requirements, or the need to choose between chat_id/message_id and inline_message_id.
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, well-structured sentence that front-loads the action and resource, listing media types concisely with no filler or redundancy.
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 mutation tool with five parameters and no output schema, the description is too high-level. It omits critical invocation details like required fields, inline-message usage, and which parameters are mutually exclusive, leaving an agent with insufficient guidance to use 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 coverage is 60%, with media and inline_message_id lacking descriptions. The description mentions media types but does not explain that media is effectively required, how inline_message_id relates to chat_id/message_id, or what reply_markup contributes in this context. It adds only marginal 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 uses the specific verb 'Edit' and identifies the resource 'media content of a message' with a clear list of media types (photo, video, animation, document, audio). This distinguishes it from sibling tools like edit_message_text, edit_message_caption, and edit_message_reply_markup.
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 editing media within a message and provides a clear context via the allowed media types. It does not explicitly name alternatives or state when not to use it, but the context is sufficiently clear for selection among 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 declare readOnlyHint=false and destructiveHint=false, so the agent knows it is a mutating but non-destructive operation. The description adds one useful behavioral detail (album grouping preservation) but says nothing about limits, return values, or error semantics. This adds some value beyond annotations but is 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 core action and a key behavioral nuance. Every word earns its place, with no repetition of schema or annotation information.
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 6 parameters (3 required), only 17% schema coverage, and no output schema, the description is too minimal to fully orient the agent. It covers purpose and one behavioral trait, but omits parameter roles, return format, and any operational constraints, leaving significant gaps for a mutation 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?
Schema description coverage is only 17%, with chat_id being the only parameter described. The description does not explain the meaning of from_chat_id, message_ids, message_thread_id, disable_notification, or protect_content. It only implies 'messages' are forwarded, but fails to compensate for the sparse 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 ('Forward'), names the resource ('messages'), and includes a scoping qualifier ('multiple at once'). The parenthetical '(maintains album grouping)' distinguishes it from the sibling forward_message and copy_messages 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 phrase 'multiple messages at once' clearly implies use for batch forwarding, and 'maintains album grouping' sets expectations about behavior when forwarding albums. However, it does not explicitly state when to prefer forward_message or copy_messages, so it stops short of full exclusion/alternative 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 indicate a non-read-only, non-destructive action. The description adds the 'album' behavior and the 2-10 item count, but does not disclose potential effects, required permissions, or error conditions. This is a modest improvement 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 front-loads the main purpose and key 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.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, low schema coverage, no output schema), the description is insufficient. It does not clarify the media array requirements, optional parameters, or expected result, leaving significant gaps 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 only 30%, with critical parameters like 'media' left undescribed ('{}'). The description names media types but does not explain the structure of the media array, which is essential for correct invocation. It 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 a specific action: sending multiple media items (photos, videos, documents, audios) as an album, with a 2-10 item constraint. It distinguishes this from single-media send tools like send_photo and send_video.
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 the tool: when sending 2-10 media files as an album. However, it does not explicitly state when not to use it or mention alternatives for single media sends, so it falls short of full exclusions 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 indicate a non-read-only, non-idempotent operation, lowering the baseline. The description adds the constraint 'max 1 minute', which is useful behavioral context about media limits. However, it does not disclose potential errors, authentication requirements, or other behavioral nuances 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 a single clear sentence with no wasted words. It immediately states the action and adds a clarifying parenthetical without redundancy.
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 having 13 parameters, no output schema, and only basic annotations, the description is extremely brief. It does not mention required parameters, return behavior, or common optional fields. For a complex send operation, this is insufficient for an agent to handle edge cases or understand side effects.
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 coverage is only 38%, and the description does not compensate for the 8 undocumented parameters. It only hints at the duration limit via 'max 1 minute', but does not explain parameters like thumbnail, effect_id, or reply_markup. This is insufficient for an agent to correctly use the full parameter set.
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's function: 'Send a video note' with the clarifying parenthetical '(round video message, max 1 minute)'. This distinguishes it from siblings like send_video and send_voice by specifying the unique media format.
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 the tool (for round video messages) and implies not to use it for regular videos. However, it does not explicitly name alternatives like send_video, though the mention of 'round video message' is sufficient for basic differentiation.
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 readOnly=false, idempotent=true, destructive=false. The description adds the auth requirement, which is useful context, but it does not disclose potential side effects like overwriting existing statuses or invalid emoji behavior. It's consistent with annotations but not deeply transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 17 words. It is front-loaded with the action and resource, and the parenthetical adds the key prerequisite. No wasted words.
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 three parameters and no output schema, this description is too sparse. It leaves the meaning of the expiration date and emoji ID parameters completely unexplained. Annotations provide some safety cues, but the description itself does not give enough operational context to use the tool confidently.
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 only 33% (only user_id is described). The description does not mention any of the three parameters, leaving emoji_status_custom_emoji_id and emoji_status_expiration_date undefined. With such low coverage, the description needed to compensate but failed to do so.
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 'Set' and the target 'custom emoji status for a user', which is specific and distinct from sibling tools like set_chat_title or set_sticker_emoji_list. The permission requirement adds clarity about the operation's 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 prerequisite ('requires bot to have appropriate rights') and the name/description make the intended use obvious. There are no direct sibling alternatives for this specific operation, so no exclusions are needed.
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 states that only the name is edited, which is consistent with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false). It adds no additional behavioral context beyond the annotation-provided safety profile.
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 unnecessary information. It is instantly understandable and well-scoped.
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 2-parameter mutation with no output schema, the description adequately covers the essential scope and purpose. It does not need to explain return values or complex behaviors, though it could mention prerequisites like admin rights.
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 50%: chat_id has a description but name does not. The description partially compensates by indicating 'name' is the new name of the General topic, but does not elaborate on format or constraints beyond schema min/max length.
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 'Edit' and clearly identifies the resource: 'name of the ''General'' forum topic'. This distinguishes it from sibling tools like close_general_forum_topic or edit_forum_topic, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for renaming the General forum topic, but does not explicitly mention alternatives or when not to use it. It lacks direct comparison with edit_forum_topic or other topic-related 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 declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds useful context about the kind of data returned (title, description, photo, etc.) but does not disclose additional behavioral traits like auth requirements or rate limits.
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 communicates the tool's purpose. Every element ('full information', example fields) earns its place 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 getter with one parameter and strong annotations, the description is adequately complete. It outlines the expected content of the response, though it does not detail the exact return structure (no output schema exists), which is acceptable given the low 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 schema covers 100% of the parameter documentation: chat_id is described as 'Chat ID or @username'. The description adds no parameter-specific meaning, but the schema fully compensates, so the baseline score of 3 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 uses a specific verb 'Get' and identifies the resource 'chat' with a clear scope ('full information'), listing example fields. This distinguishes it from sibling tools like get_chat_administrators or get_chat_member_count, which target specific aspects.
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 full chat information is needed, but does not explicitly state when not to use it or mention alternatives. Sibling tools for specific subsets exist, but no guidance is provided for choosing between them.
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 clear. The description adds no extra behavioral context beyond the version note '(v9.1)', which is minor and does not meaningfully disclose 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 efficiently conveys the tool's purpose and even includes a version reference. 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?
This is a simple, parameterless read operation with strong annotation coverage. The description is sufficient for an agent to understand the tool's basic function. It doesn't explain the return format, but for a balance query this is not a significant gap.
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 zero parameters, the schema fully documents the input. The baseline for no parameters is 4, and the description adds no redundant parameter details, 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 states the tool's purpose: retrieving the bot's Telegram Stars balance. It uses a specific verb ('Get') and resource ('bot's Telegram Stars balance'), and the scope ('bot's') distinguishes it from the sibling 'get_business_account_star_balance'.
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 like get_business_account_star_balance. The description only states what it does, not the 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=false, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe (non-destructive) write operation. The description adds no additional behavioral context beyond the verb 'reopen', but 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, direct sentence with no filler or redundant phrasing. It is efficiently front-loaded with the action and target.
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 (one parameter, no output schema) and the description accurately states the operation. It lacks context about forum prerequisites or state changes, but given low complexity and available annotations, it is reasonably complete.
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 fully documents the single chat_id parameter with type and description ('Chat ID or @username'), so the description need not repeat parameter details. Schema coverage is 100%, so baseline 3 applies.
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 ('reopen') and identifies the resource ('the 'General' topic'), clearly distinguishing this from the sibling tool 'reopen_forum_topic' which handles regular forum topics. The scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/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 given. The phrase 'the 'General' topic' implies this is for the general forum topic only, but it does not explicitly contrast with 'reopen_forum_topic' or state conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it is a write operation (readOnlyHint=false), idempotent, and not destructive. The description adds the timing context of 'when adding bot', which is useful, but does not disclose other behavioral aspects such as whether it overrides existing defaults or requires special permissions. This is a moderate addition 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, front-loaded sentence that is concise and directly to the point. Every word adds value, and there is no unnecessary information.
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 optional params, no output schema), the description covers the basic purpose and timing, but the lack of explanation for the 'rights' parameter and the 'for_channels' boolean leaves gaps. The annotations partially compensate, but the tool remains somewhat opaque for an agent needing to invoke it 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?
The schema has 0% description coverage, and the description does not explain the 'rights' parameter (an empty object in the schema) or 'for_channels'. The only hint is the phrase 'groups/channels' in the description, which loosely maps to 'for_channels' but provides no real semantics. This is insufficient for an agent to construct correct 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 verb 'Set' and the resource 'default admin rights', and specifies the context 'when adding bot to groups/channels'. This distinguishes it from siblings like get_my_default_administrator_rights and set_chat_administrator_custom_title.
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 clear context for when this tool applies (when adding bot to groups/channels), which implicitly highlights its purpose relative to getters. However, it does not explicitly mention alternatives or any exclusions, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate that the tool is a write, idempotent, and non-destructive. The description adds useful behavioral context about where the description appears (empty chat). It does not contradict the annotations and is transparent about the tool's effect.
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 core purpose without any filler or redundancy. It is well-structured 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 simplicity (two basic string parameters, no output schema), the description provides the essential purpose but omits details about the return value and the semantics of language_code. It is adequate but not fully complete for an agent to use without prior 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?
Schema coverage is 0%, and the description does not mention the parameters at all. The 'description' parameter is somewhat obvious from the tool name, but 'language_code' is not explained (e.g., for localization). The description fails to add meaning beyond the schema's basic property 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 clearly states the action ('Set the bot's description') and provides specific context ('shown in empty chat') that distinguishes it from related tools like set_my_short_description and get_my_description. 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives contextual information ('shown in empty chat') that implies when this tool is relevant, but it does not explicitly state when to use this versus alternatives such as set_my_short_description. No direct exclusions or alternative mentions 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 convey that this is a mutating, non-destructive, idempotent operation. The description adds the 'open topic' precondition, which is useful, but does not disclose permission requirements, error behavior on closed topics, or any other behavioral nuance beyond 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence with no waste. The key information is front-loaded: verb, object, and context.
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 simple nature of the operation, the two fully documented parameters, and the presence of annotations covering idempotency and destructiveness, the description is sufficient for a basic close operation. No output schema is needed to invoke the tool 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 already fully documents both parameters with descriptions (chat_id type/format, message_thread_id semantic). The description adds no parameter-specific guidance, so it relies entirely on the schema's 100% 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 (close) and the target resource (an open topic in a forum supergroup), distinguishing it from sibling tools like reopen_forum_topic, delete_forum_topic, and close_general_forum_topic. No ambiguity about what operation is performed.
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 closing currently open topics in forum supergroups but does not explicitly state when to use it instead of alternatives such as close_general_forum_topic or how to handle already-closed topics. No explicit usage guidelines or exclusions are provided beyond the core 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?
Annotations already indicate destructive and non-read-only behavior, and the description adds the important context that the bot must have delete rights. While it does not discuss failure modes or irreversibility beyond the annotation, the permission requirement adds meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, with the core action front-loaded and the prerequisite immediately following. No waste, and the structure is highly scannable.
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 delete operation, the description covers the core action and the key precondition (delete rights). Annotations fill in the destructive nature. It omits return value or error handling, but with annotations and a straightforward use case, this is adequately 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 schema provides a description for chat_id but not for message_id (50% coverage). The tool description does nothing to clarify parameter meanings or relationships, failing to compensate for the low schema coverage. Both parameters are left mostly implicit.
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 'Delete a message' uses a specific verb and resource, with the singular 'a message' clearly distinguishing it from the sibling tool 'delete_messages' (plural). The action is unambiguous and directly maps to 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?
The description clarifies when the tool is applicable by stating 'Bot must have delete rights in the chat,' which is a necessary prerequisite. However, it does not explicitly mention when to use the alternative 'delete_messages' for bulk deletion, leaving alternative-selection guidance implicit.
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, so the description need not restate that deletion is destructive. It adds a useful constraint (Max 100 messages), but provides no additional context about permissions, irreversibility, or behavior when some message IDs are invalid—an acceptable minimum given 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 two short sentences, front-loaded with the action and resource, and every word adds value. There is zero redundancy or filler.
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 two-parameter batch deletion tool, the description covers the core action and limit, but omits potential details like required permissions or error behavior. Given the simplicity and existing annotations, it's minimally viable but not fully complete.
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 already provides descriptions for 'chat_id' (Chat ID or @username) and sets min/max items on 'message_ids'. The description reinforces the batch aspect ('multiple', 'Max 100'), but does not add significant new meaning beyond the schema constraints. Baseline 3 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 uses a specific verb ('Delete') and resource ('multiple messages'), clearly distinguishing this batch tool from the sibling 'delete_message' for single deletions. The 'at once' qualifier clarifies the tool's batch nature, and 'Max 100 messages' adds a precise 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 phrase 'Delete multiple messages at once' clearly establishes the use case for batch deletion, distinguishing it from single-message deletion tools. While it does not explicitly name alternatives or exclusion cases, the context is clear enough for an agent to select this tool over individual 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 provide the core behavioral hints (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds the fields being edited but does not elaborate on permission requirements, side effects, or partial-edit behavior. 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 single, efficient sentence that front-loads the key action and resource. No redundant or extraneous words.
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 four parameters (two required) and useful annotations, but no output schema. The description covers the core purpose but does not address optionality (e.g., whether at least one of name/icon is needed), permissions, or additional edge cases. It is minimally adequate for a straightforward edit 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 description clarifies that 'name' refers to the forum topic's name and that the icon corresponds to icon_custom_emoji_id, which is valuable since the schema lacks descriptions for these two optional parameters. The required parameters (chat_id, message_thread_id) are already described in 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 ('Edit') and the resource ('forum topic'), along with the specific aspects affected ('name and icon'). It is concise and distinguishes the tool from siblings like create_forum_topic, delete_forum_topic, and edit_general_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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (editing a forum topic's name/icon) but does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions like 'only for regular topics, not general topics.' There is no alternative 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 indicate this is a safe, read-only, idempotent operation. The description adds the scoping qualifier 'can be sent,' but no additional behavioral context (e.g., authentication, pagination, global scope). It provides marginal 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 clear sentence with no superfluous words. It is front-loaded and appropriate for a tool with no parameters and simple semantics.
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 strong annotations, but the description does not explicitly clarify that this returns a global catalog rather than user- or chat-specific gifts. With several similar sibling tools, a bit more context would improve completeness.
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 takes zero parameters, so the schema trivially covers everything. The description adds no parameter details, but none are needed. Baseline of 4 is appropriate 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 states the exact resource (list of gifts) and the qualifier 'can be sent' clearly distinguishes it from sibling tools like get_user_gifts or get_chat_gifts. 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'that can be sent' implies this is the catalog of available gifts, but it does not explicitly state when to use this vs. alternatives such as get_user_gifts or get_business_account_gifts. Usage context is implied, 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 readOnlyHint, idempotentHint, and non-destructive nature. The description adds behavioral context by explaining that the result is a file_path and showing how to construct the download URL (including the bot token placeholder). This goes beyond the annotations and clarifies the output's usage, warranting a 4.
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, front-loaded sentences with no waste. The first sentence states the action and purpose; the second provides the download URL template. 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?
Given the tool's simplicity (one parameter, no output schema, read-only), the description covers the core purpose and the return value usage. It would benefit from a mention that file_id originates from a message or other source, but overall it is sufficiently complete for a straightforward getter.
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 input schema has one required parameter (file_id) with no description, and the description provides zero explanation of what file_id is or how to obtain it. With schema coverage at 0%, the description does not compensate, leaving the agent to guess the parameter's 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?
Description states a specific action ('Get file info for downloading') and identifies the resource (file info). It clearly distinguishes from sibling tools like download_file by framing this as the info-gathering step, and the provided URL template reinforces the tool's role.
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 workflow: use get_file to obtain file_path, then download via the URL. It does not explicitly name alternatives or exclusions, but the context and the download URL indicate when this tool is relevant. Lacks explicit 'use when' language, but the purpose is clear enough.
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, destructiveHint=false, so the agent knows it's a safe read operation. The description adds no additional behavioral context beyond the basic 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 entire description is a single concise sentence that immediately conveys the tool's purpose, with 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 simple get operation with two well-documented parameters and safety annotations, this one-sentence description is sufficient; no output schema is needed since return values are not complex.
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 100% and both parameters are clearly documented in the schema, so the description adds no extra parameter semantics; baseline 3 applies.
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), the resource (user's boosts), and the scope (in a chat), which distinguishes it from sibling tools like get_user_gifts or get_chat_gifts.
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 need to retrieve a user's boosts in a specific chat, but it does not explicitly mention alternatives or when not to use it, so it's implied guidance only.
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 non-read-only, idempotent operation. The description adds the behavioral nuance that chat_id is optional, allowing either a private-chat-specific button or the default button; however, it doesn't mention any side effects or prerequisites.
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 with a clear verb, no redundancy, and gets straight to the point. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the operation is simple, the description lacks essential information about the menu_button object format and leaves the chat_id optionality implicit. For a tool with an untyped object parameter and no output schema, this is insufficient 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 schema provides no descriptions (0% coverage). The description hints that chat_id is optional (private chat vs default), which adds some semantics, but completely omits any explanation of the menu_button parameter's structure or allowed values, leaving 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 action ('Set') and the target resource ('bot's menu button'), and specifies the scope ('in a private chat or default menu button'). This distinguishes it from sibling tools like get_chat_menu_button and other set_* commands.
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 by specifying the context (private chat or default), which is a clear scope limitation. However, it does not explicitly name alternatives or provide when-not-to-use guidance, though the purpose is self-evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations covering read/write/idempotency hints (readOnly=false, idempotent=false), the description adds the meaningful behavioral difference of omitting the 'Forwarded from' header. It also discloses that captions can be changed, going 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 one focused sentence with no filler. It front-loads the core action and adds a key differentiator in parentheses, earning 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?
The description defines the core purpose and one option, but with 12 parameters and no output schema, it leaves out information about return values, optional parameters, and edge cases. For an agent to use this tool confidently, more context about behavior and return format would be helpful.
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?
Only the 'caption' parameter is addressed ('Can change caption'), while 12 parameters exist and schema description coverage is only 8%. The description fails to clarify the required parameters (chat_id, from_chat_id, message_id) or other optional ones, so it does not 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 uses a specific verb and resource ('Copy a message') and immediately distinguishes itself from forwarding by noting 'sends without Forwarded from header'. It also clearly positions itself against the plural copy_messages tool by adding 'Can change caption'.
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 explains a key use case ('sends without Forwarded from header'), which implies when to use this over forward_message. It also mentions caption capability, offering clear context for selection. However, it does not explicitly state when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating operation. The description adds a key behavioral nuance: the sticker set must have been created by the bot, which is a prerequisite not captured by the annotations. It does not describe irreversibility or error handling, but given the annotation coverage, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource. It contains no unnecessary words or redundancy. Every part 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?
For a one-parameter tool with no output schema, the description is brief but sufficient to convey the primary purpose. However, it omits details about return values, behavior when the sticker set does not exist, or consequences beyond deletion. Given the destructive nature and minimal schema, a bit more context would be helpful, but the current state is not severely inadequate.
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 coverage (0%) and the only parameter is 'name' with no description. The tool description does not explain what 'name' refers to (e.g., the name of the sticker set to delete), leaving the agent to infer from the tool name. This is a significant gap since the description should compensate for the lack of schema-level 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 ('a sticker set'), with a qualifier ('created by the bot') that distinguishes it from deleting stickers within a set (delete_sticker_from_set) or deleting chat sticker sets (delete_chat_sticker_set). This is a specific verb+resource pairing that makes the tool's function 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: to delete a sticker set that the bot created. This helps differentiate from sibling tools that handle individual stickers or other sticker-related operations, but it does not explicitly mention alternatives or when not to use it. Still, the context is clear enough for a simple delete 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 indicate destructiveHint=true and readOnlyHint=false. The description adds behavioral context by stating the effect 'switch back to getUpdates', which is useful. However, it does not explain the drop_pending_updates parameter or other side effects, so it does not fully disclose 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, front-loaded with the action 'Remove webhook integration', and contains no unnecessary words. Every word contributes to understanding.
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 one optional boolean parameter and no output schema. The description explains the core purpose but omits the parameter's behavior and potential edge cases. Given the simplicity, 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 one parameter, drop_pending_updates, with no description (0% schema coverage). The description does not mention this parameter, providing no guidance on its meaning or usage. Since coverage is low, the description must compensate, but it fails to do so.
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 webhook integration' and its consequence 'switch back to getUpdates', using a specific verb and resource. It distinguishes from siblings like set_webhook and get_webhook_info by indicating the removal and fallback to polling.
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 use case: use when you want to stop using a webhook and revert to getUpdates. It provides clear context but does not explicitly mention alternatives or exclusions, earning a 4 rather than a 5.
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 read-only, idempotent, and non-destructive behavior. The description adds no additional behavioral context such as return format, pagination, or authentication requirements. With annotations covering safety, the description contributes little beyond purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It efficiently conveys the tool's purpose and intended use.
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, parameterless retrieval tool, the description provides sufficient context about what the tool does and its use case. No output schema exists, but the description tells the agent the tool returns custom emoji stickers. It is complete enough for basic 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?
The tool has no parameters, and the schema coverage is 100%. Per the baseline for zero-parameter tools, the description doesn't need to explain parameters. It appropriately focuses on 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 the tool retrieves custom emoji stickers specifically for use as forum topic icons. The verb 'Get' and resource 'custom emoji stickers' are specific, and the 'forum topic icons' qualifier distinguishes it from sibling tools like get_custom_emoji_stickers.
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 needing emoji stickers for forum topic icons. It provides clear context but does not explicitly mention alternatives or exclusions. Since the purpose is narrow, an agent can infer usage.
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 description does not contradict them. However, it adds no behavioral context beyond the annotations, such as what happens if the sticker set does not exist or how the result is returned.
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, clear sentence that front-loads the action and resource. There is no unnecessary information, making it highly concise 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 such a simple tool with one parameter and rich annotations, the description is complete enough. It clearly states what the tool does and how the parameter is used, though it does not describe the return value or error handling, which is not critical for a basic getter.
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 explicitly states the set is retrieved 'by name', giving semantic meaning to the single parameter. This compensates for the lack of parameter documentation in the schema, though it does not elaborate on format or 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 clearly states the action ('Get') and the resource ('sticker set') with the method of identification ('by name'). It is specific and distinguishes itself from sibling tools like get_custom_emoji_stickers or delete_sticker_set.
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 tool's purpose is clear, but the description does not provide explicit guidance on when to use it over alternatives. No exclusions or alternative tool references are given, though the simplicity of the tool makes its usage fairly 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=true, idempotentHint=true, and destructiveHint=false. The description adds that the log tracks posted/failed/skipped statuses across pipelines, but does not disclose additional behavioral traits like pagination limits or response format. 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?
Two concise sentences, front-loaded with the main verb and resource, and no wasted words. Every sentence contributes to understanding.
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 well-documented schema and strong annotations, the description covers the essential purpose. It lacks explicit mention of the return format, but for a read-only query tool with no output schema, the description is sufficient for agent invocation.
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 100%, so all 7 parameters are already fully documented in the schema. The description does not add any parameter-specific meaning beyond what the schema provides, so baseline 3 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 states the tool queries the TRAIL content log and specifies what it checks (posted, failed, or skipped content across pipelines). This distinguishes it from siblings like get_trail_stats (statistics) and mark_trail (marking entries).
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 clear context for use: inspecting content log entries by status. It does not explicitly mention exclusions or alternatives, but the purpose is unambiguous enough for an agent to decide when to invoke this tool.
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 the tool is not read-only, not idempotent, and not destructive, and the description consistently describes a write operation. It adds context about the TRAIL log but does not disclose additional behavioral traits such as append-only semantics, duplicate-entry behavior, or whether any constraints apply. With annotations present, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, no filler. The first sentence states the core action and target, and the second clarifies the intended use. 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?
The tool is a simple log writer, and the description plus schema and annotations cover the main aspects: what it does, when to use it, and what parameters are needed. It could additionally mention the return value or that entries are retrievable via get_trail, but the absence is not a critical gap for this low-complexity 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 input schema has 100% coverage with descriptions for all six parameters, including the required content_id, action, and requester. The description adds no parameter-specific information, so the baseline score of 3 applies.
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 ('Write') and identifies a distinct resource ('TRAIL content log'), and it differentiates from sibling read tools like get_trail and get_trail_stats by clearly indicating this is a write operation. The scope ('record content actions') further clarifies what kind of entries are written.
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: 'Use to explicitly record content actions.' It does not explicitly mention when not to use the tool or name alternatives, but the stated purpose is sufficient context for selecting it over the read-focused 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the specific fields returned (id, name, username), which is useful but minimal. No additional behavioral traits (e.g., rate limits, auth) are 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, front-loaded sentence with no filler. It efficiently conveys the tool's purpose and what it returns.
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 (no parameters, no output schema) and the annotations already providing safety context, the description is complete. It names the resource (the bot) and the expected return fields, which is sufficient 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.
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 does not need to explain parameter semantics, and no parameters exist to document.
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: 'Get basic information about the bot,' and provides concrete examples (id, name, username). This distinguishes it from sibling tools that operate on other resources (e.g., get_my_commands, get_chat).
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 need the bot's own basic profile data, but does not explicitly mention when not to use it or alternatives. The context is clear enough for a standard 'get_me' tool, so it merits an 'implied usage' score, not a lower one.
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 mutable, non-destructive, idempotent operation), the description adds a key behavioral constraint: edits are only allowed on messages sent by the bot or via inline mode. This informs the agent of a critical eligibility rule not present in the schema or 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 states the action and scope. No waste, and it is front-loaded with the verb 'Edit'.
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 text-editing tool, the description covers the essential non-schema information (message ownership constraint). It does not explain the return value or the need for chat_id/message_id vs inline_message_id, but the schema handles those, and the tool is simple enough that 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 schema description coverage is high (88%), so the description does not need to explain parameters. The description does not add any additional meaning beyond what the schema already provides, matching the baseline score for high 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 uses a specific verb (Edit) and identifies the exact target (text of a message), while adding the critical scope restriction that only messages sent by the bot or via inline mode are editable. This clearly distinguishes it from sibling tools like edit_message_caption or edit_message_media.
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?
It provides clear context by indicating that this tool is for changing the text of messages the bot owns. However, it does not explicitly state when not to use it or name alternatives, though the scope restriction implicitly separates it from caption/media editing 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, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context beyond annotations by specifying that the tool works 'for a chat or default,' implying that chat_id is optional and a default is returned when omitted. This is useful and non-contradictory.
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, clear sentence with no unnecessary words or repetition. It front-loads the action and resource, making it highly scannable for an agent.
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?
This is a simple getter with one optional parameter and rich annotations. The description is sufficient to understand the core function, though it does not describe the return format. Since there is no output schema, a bit more detail about the return value could be helpful, but it is not critical for such a straightforward read 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?
There is only one parameter (chat_id) with no schema description, and the description covers 0% of schema details. However, the phrase 'for a chat or default' adds meaning by signaling that chat_id is optional and that omitting it returns the default menu button. This 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 the tool 'Get the current menu button for a chat or default.' It uses a specific verb ('Get') and resource ('menu button'), and clarifies the scope ('chat or default'). This distinguishes it from sibling tools like set_chat_menu_button and get_chat.
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 the menu button, but it does not explicitly mention when to use it instead of alternatives. There is no reference to set_chat_menu_button or other related tools, so guidance relies on the verb 'Get' and the tool 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, destructiveHint=false, and idempotentHint=true, covering safety. The description adds minimal behavioral context beyond stating it's a read operation, which is consistent with annotations. No contradiction, but no extra details like return format 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 front-loads the action and resource. Every word contributes meaning, 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 getter with one parameter and strong annotations, the description is adequate. It lacks explicit return value information, but given the straightforward nature of the tool and the readOnly/idempotent annotations, the context is sufficiently complete for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description's 'by their identifiers' maps directly to the single parameter custom_emoji_ids, clarifying its purpose. Since the schema provides no description for the parameter, this contextual hint adds meaning, though it doesn't elaborate on the format or expected structure of the IDs.
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 operation ('Get information') and the specific resource ('custom emoji stickers'), with the method ('by their identifiers'). This distinguishes it from sibling tools like get_sticker_set or get_forum_topic_icon_stickers, 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 implies usage context: call this when you have identifiers for custom emoji stickers and need their information. It doesn't explicitly exclude alternatives, but the resource is specific enough that no confusion arises with sibling 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds no extra behavioral context beyond 'current', but it aligns with annotations 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 a single sentence, front-loaded, and contains no filler. 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?
The tool is simple with no parameters and strong annotations. Though there is no output schema, the description adequately communicates the tool's purpose for selection. It could mention what 'status' includes, but the simplicity of the tool keeps the description sufficient.
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 needs no parameter details. The schema is empty and 100% covered; with no params, baseline is 4, and the description does not need to compensate.
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 'Get current webhook status' uses a specific verb ('Get') and resource ('webhook status'), clearly distinguishing it from sibling tools like set_webhook or delete_webhook. It immediately conveys what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 when you need the current webhook status, which is a read-only operation. It doesn't explicitly mention alternatives or exclusions, but the context is clear enough given the sibling set/delete 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 provide basic safety signals (idempotent=true, destructive=false), and the description adds the usage context but doesn't disclose additional behavioral traits like what closing entails or side effects. Since annotations cover the safety profile, a score of 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 two short sentences with no fluff. It is front-loaded with the action and followed by a practical usage note. 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?
For a simple parameterless tool with good annotations, the description fully covers purpose and usage context. It is complete enough for an agent to select and invoke it correctly without further clarification.
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 coverage is trivially 100%. The description doesn't need to explain parameters, earning the baseline of 4 for no-parameter tools.
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 ('Close') and the resource ('the bot instance'), which is specific and distinct from sibling tools like log_out or get_me. It unambiguously identifies what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Use before moving between local servers' provides explicit guidance on when to use the tool. While it doesn't mention alternatives or exclusions, the context is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 important behavioral context by stating 'along with all its messages,' disclosing that the operation cascades to delete all contained messages. This goes beyond the annotations and clarifies the full destructive impact.
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 action and resource. Every word contributes meaning, with no filler or redundancy.
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 (only 2 required parameters, complete schema coverage, and clear annotations), the description adequately covers the essential context: it identifies the action, the target, and the cascading effect on messages. No output schema exists, and none is needed for this straightforward deletion 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 already provides 100% parameter description coverage: chat_id is 'Chat ID or @username' and message_thread_id is 'Forum topic thread ID'. The description does not add additional parameter-level meaning beyond what the schema already documents, so the baseline score of 3 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 uses a specific verb and resource: 'Delete a forum topic along with all its messages.' It clearly states the action and scope, distinguishing it from sibling tools like delete_message/delete_messages (which delete individual messages) and close_forum_topic (which closes rather than deletes).
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 the tool: when you want to permanently remove a forum topic and its messages. However, it does not explicitly mention alternatives or when not to use it, such as using close_forum_topic instead if the topic should be preserved but hidden.
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 readOnlyHint=false and destructiveHint=false, but the description adds valuable behavioral context: 'Saves locally' (side effect on filesystem), 'returns the path' (output behavior), and 'Max 20MB (Telegram Bot API limit)' (constraint). This goes beyond 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?
Two sentences, front-loaded with the primary action and immediate outcome. Every clause earns its place: download mechanism, result, usage context, and size limit. No fluff 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 two-parameter tool with full schema coverage and no output schema, the description is complete. It covers usage timing, size constraint, and return value (path), giving the agent enough context to invoke the tool correctly without needing return format details.
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 100%, with both file_id and dest_dir clearly documented. The description adds no additional parameter-level detail beyond what the schema already provides, so a baseline of 3 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?
Description explicitly states 'Download a file from Telegram by file_id' with a specific verb (download), resource (file), and mechanism (file_id). It also adds outcome ('Saves locally and returns the path'), making it unambiguous and distinct from siblings like get_file which likely only retrieves metadata.
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 on when to use: 'Use after receiving a message with a photo, video, document, voice, etc.' It does not explicitly mention alternatives or exclusions (e.g., 'for metadata only, use get_file'), so it falls short of a 5 but is well above no 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?
The description adds the workflow context of switching to a local server, which is useful beyond the annotations. However, it does not disclose details about session invalidation or post-logout behavior. The annotations (idempotentHint: true, destructiveHint: false) already provide a safety profile, so the description adds modest value.
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 a specific usage tip. Every word earns its place, and there is no redundancy or vague 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?
Given the tool's simplicity (zero parameters, no output schema) and the annotations covering safety traits, the description is complete. It states what the tool does and when to use it, which is sufficient for a logging-out utility.
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 the schema coverage is 100% (vacuously). The description does not need to explain parameters, and none are present. The baseline of 4 for a zero-parameter tool applies, as there is nothing to compensate for.
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 ('Log out') and the specific target ('cloud Bot API server'), making the tool's purpose unambiguous. It distinguishes itself from siblings by focusing on session termination on the cloud server, which is not covered by other 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 an explicit usage scenario: 'Use before moving to a local server.' This gives clear context for when to invoke the tool, though it does not explicitly mention alternatives or when not to use it. The guidance is sufficient for a zero-parameter utility.
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?
The description explicitly discloses the destructive effect by stating 'revokes previous one', which directly aligns with the annotations destructiveHint=true and readOnlyHint=false. It adds specific context about what gets destroyed beyond the generic 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 a single sentence containing only necessary information: 'Generate a new primary invite link (revokes previous one).' It is front-loaded, concise, and free of 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 with no output schema, the description covers the core behavior and its destructive side effect. It does not explicitly state the return value (presumably the new invite link), but this is a minor gap given the tool's low complexity and the fact that the only parameter is already fully documented.
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 fully documents the only parameter 'chat_id' with description 'Chat ID or @username', achieving 100% schema coverage. The tool description adds no additional parameter semantics, so the baseline score of 3 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 uses the specific verb 'Generate' with the resource 'primary invite link', and explicitly states the side effect 'revokes previous one'. This distinguishes it from sibling tools like create_chat_invite_link (secondary links) and revoke_chat_invite_link (revoking arbitrary 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 provides clear context that this is for generating the primary invite link, implying it's the go-to for primary link replacement. However, it does not explicitly mention when to use this instead of create_chat_invite_link or revoke_chat_invite_link, so no explicit exclusion is given.
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:

[![telegram-api-mcp MCP server](https://glama.ai/mcp/servers/timoncool/telegram-api-mcp/badges/card.svg)](https://glama.ai/mcp/servers/timoncool/telegram-api-mcp)

Score Badge

Copy to your README.md:

[![telegram-api-mcp MCP server](https://glama.ai/mcp/servers/timoncool/telegram-api-mcp/badges/score.svg)](https://glama.ai/mcp/servers/timoncool/telegram-api-mcp)

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/timoncool/telegram-api-mcp'

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