Server Quality Checklist

Tool Scores

• delete_messageC
  2.9/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden of behavioral disclosure. For a destructive mutation tool, the description gives no indication of side effects (whether deletion is permanent, whether it affects message history for other members, whether there are rate limits or permission requirements). This is a significant gap for a tool designated as destructive by its very 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?

  A single concise sentence with zero waste. Efficiently conveys the core action without extraneous detail, though the brevity means some behavioral context is sacrificed.

  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 destructive mutation tool with no annotations and no additional detail beyond a terse one-liner. While an output schema exists (which slightly reduces burden for return-value explanation), the description should address side effects, permission requirements, or permanence of deletion. The tool is simple (2 params) but the destructive nature demands more behavioral disclosure than a bare functional statement.

  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 both parameters (chat_id and message_id) are documented in the schema itself. The description adds no semantic detail beyond what the schema provides, making the baseline of 3 appropriate. The description doesn't clarify formats, limits, or relationships between the two 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 uses a specific verb (delete) plus a clear resource (message from a chat), which accurately states the function. It is distinct from siblings like send_message and edit_message_text, though the mention of 'from a chat' is somewhat an obvious qualifier for chat 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?

  No when-to-use or when-not-to-use guidance is provided. There is no mention of alternative deletion approaches, prerequisites (like whether the deleting user must be an admin/member), or cleanup ordering (e.g., must delete before chat is removed). The sibling tools offer no comparable deletion tool, but guidelines could clarify the role of this tool relative to edits or chat management.

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

• edit_message_textC
  2.9/5.0
  Behavior2/5

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

  With no annotations provided, the description carries full behavioral disclosure burden but fails to mention important traits. It doesn't state that editing may fail if the message is too old, that the message must be sent by the bot itself (Typical for Telegram bot APIs), or what happens to the original message's other properties. The mutation behavior is implicit in 'edit' but unsupported details are absent.

  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, efficient sentence with no waste. It's appropriately short for a tool whose parameters are well-covered by the schema, though it could arguably benefit from one more clause about constraints.

  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 output schema exists, so return-value documentation isn't required. However, for a mutation tool with zero annotations, the description is thin — it doesn't cover edit limitations (time windows, message must be from the bot), constraints, or when edits silently fail. It's minimally viable but leaves meaningful gaps for an agent deciding whether a requested edit is feasible.

  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 the schema already documents all 4 parameters. The description adds virtually nothing beyond the schema — it doesn't explain parse_mode formatting options in more detail or add semantics about how text replacement works. Baseline 3 is appropriate since the schema handles the parameter documentation adequately.

  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+resource ('Edit the text of an existing message') which clearly identifies the action and target. It distinguishes itself from siblings like send_message (creates new) and delete_message (removes) by focusing on 'editing existing text,' though it doesn't explicitly name the 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?

  The description provides no guidance on when to use this tool vs alternatives. It doesn't mention that this only works for message types that support text editing, that edits typically only apply within Telegram's time limits (like the 48-hour rule for bot messages in some contexts), or that send_message should be used for new messages instead.

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

• get_chat_member_countC
  2.9/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden for behavioral disclosure. The description is pure tautology of the name and gives no behavioral context such as return format, whether the count reflects current membership or cached value, authentication requirements, or rate-limiting considerations. The tool reads like a simple lookup but offers no information beyond what the name already states.

  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 zero waste. It's appropriately terse for a simple tool. Being slightly too minimal rather than verbose is offset by its clarity, though it could arguably benefit from one or two more useful details.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The context signals show a simple tool: 1 parameter, 100% schema coverage, an output schema exists, no nested objects, and no annotations. With an output schema present, the description needn't explain return values. However, for a tool that counts members, some usage context (which chat types are supported, bot membership requirements) would improve completeness. Given its simplicity, it's adequate but leaves the agent guessing on edge cases.

  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 the single chat_id parameter fully documented as 'Unique identifier for the target chat or username.' The description itself adds no parameter details beyond what the schema already provides, so the baseline of 3 applies. No additional semantic guidance like accepted formats for numbers vs usernames is added.

  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 'Return the number of members in a chat' uses a specific verb (Return) with a clear resource (member count in a chat). It distinguishes from siblings well since none of the sibling tools (get_chat, send_message, etc.) are about member counts, 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?

  There is no guidance on when to use this tool versus alternatives. It doesn't mention whether this works for all chat types (private, group, supergroup, channel), any prerequisites (e.g., bot must be a member), or when one might prefer get_chat instead. 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.

• send_documentC
  2.9/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full behavioral disclosure burden. It doesn't mention what chat types are supported (private, group, channel), file size limits, whether sending fails silently or throws, or any special handling. For a tool sending files to external chats, this is a meaningful gap.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single concise sentence with zero waste. It's appropriately short, though it could benefit from one or two additional details on behavior or usage without becoming verbose.

  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 existence of an output schema and 100% schema coverage, the description is sufficient for basic invocation. However, with no annotations and a write-action tool (sending external messages), some behavioral context like auth requirements or format expectations would strengthen completeness. It's adequate but relies heavily on structured fields.

  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 four parameters (caption, chat_id, document, parse_mode) have schema-level documentation. The description adds no additional parameter semantics beyond what the schema provides, landing at the baseline of 3 for full 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 states a clear verb+resource combination ('Send a file/document to a Telegram chat'). It distinguishes the action of sending documents, which is distinct from siblings like send_message, send_photo, send_location, and send_poll, though it doesn't explicitly compare against them.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  No guidance on when to use this tool vs alternatives like send_photo (which could handle some document types) or how to choose between file URL vs file_id. No exclusions or prerequisites mentioned. The schema hints at usage but the description provides no decision context.

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

• send_photoC
  2.9/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. The description doesn't mention that photos sent as URL must be publicly accessible, that sending by file_id requires the file to originate from the same bot, or any size/format restrictions. It doesn't describe what the response returns or whether this mutation is reversible. For a write operation with zero annotation support, this is a significant gap.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  A single sentence with zero wasted words. Every element earns its place. It's appropriately terse and front-loaded with the core action first.

  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 a 100% schema coverage and output schema presence, the tool has no annotations and its description is minimal. Sending media via Telegram involves nuances the agent should know (URL accessibility requirements, file_id constraints, size limits, whether photo upload or send-by-reference) that are entirely absent. For a message-sending tool with behavioral subtleties, this is incomplete.

  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 the schema documents all 4 parameters thoroughly (chat_id targets, photo as URL or file_id, caption limits, parse_mode formatting). The description itself adds no parameter explanations beyond the schema. Baseline 3 is appropriate since the schema handles documentation fully.

  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 photo to a Telegram chat" uses a specific verb (send) with a specific resource (photo) and destination (Telegram chat). It clearly distinguishes from siblings like send_message, send_document, send_location, and send_poll. However, it's slightly terse and doesn't elaborate on the type of photo input accepted, though 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 on when to use this tool vs. alternatives like send_document for images, or send_message. The description doesn't state when to prefer a URL vs. file_id, or clarify distinctions between photo and document sending. There's an implied context (sending photos to chats) but no explicit when-to-use or when-not-to-use guidance.

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

• send_pollB
  3/5.0
  Behavior2/5

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

  No annotations are provided, so the description bears the full burden of behavioral disclosure. The description reveals nothing about side effects—it doesn't mention whether sending requires admin rights, whether polls can be edited later, whether the poll is permanently posted, or what the response looks like. This is a meaningful gap for a tool that creates persistent content in an external system.

  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 zero wasted words. It's front-loaded and clear. It could arguably add more operational detail while staying concise, but for pure conciseness this is appropriately lean.

  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 that posts to an external chat with no annotations and no behavioral context, the description is too thin. While an output schema exists (which reduces the need to explain return values), the absence of any guidance about message limits, whether the poll appears to all members, or how this relates to edit_message_text to correct a misposted poll leaves the description under-complete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the baseline is 3. The description itself adds no parameter details beyond the schema, but the schema is fully self-documenting with clear definitions for chat_id, options, question, and booleans, including defaults and character limits. The high schema coverage plus defaults for optional parameters makes this well-served without extra description text.

  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 poll to a Telegram chat' clearly states the verb (send), resource (poll), and destination (Telegram chat). It distinguishes from siblings like send_message and send_photo by specifically targeting polls. However, it doesn't elaborate on distinguishing features vs sibling send tools beyond the resource type, so it stops short of a 5.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage 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 simply states what it does without mentioning context or any exclusions. Since this is a Telegram integration with many sibling send/edit/delete tools, the agent receives no differentiation guidance for selection decisions.

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

• send_locationB
  3.2/5.0
  Behavior3/5

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

  No annotations are present, so the description carries the behavioral disclosure burden. It clearly signals a write/action operation ('Send'). It doesn't describe what happens on success/failure, whether the location renders as an interactive map in Telegram, or any rate-limiting/auth specifics, but for a simple send action the disclosure is minimally adequate.

  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?

  A single concise sentence that conveys the core action without waste. It could add value with sibling differentiation, but as written it is efficient. Slightly more context could elevate it further without bloating.

  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?

  There is an output schema, so return-value documentation is not needed. For a straightforward 4-param send tool, the description plus full schema coverage is largely sufficient. However, it lacks any guidance on appropriate usage context or edge cases (e.g., horizontal_accuracy constraints), so it's adequate but not thorough.

  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 4 parameters are documented in the schema. The description adds no additional parameter meaning beyond what the schema already provides (chat_id, latitude, longitude, horizontal_accuracy are all individually described). Baseline 3 is appropriate since the 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 states a clear verb+resource ('Send a geographic location to a Telegram chat'). It differentiates from send_message/send_photo/send_document siblings by specifying the geographic-location payload. However, it doesn't explicitly name sibling alternatives or highlight that this is the location-specific option among the 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?

  No guidance on when to use this vs alternatives. The agent must infer that it's for locations specifically. No exclusions or context about prerequisites (e.g., does the chat need to accept locations, any chat type limitations) are provided.

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

• send_messageB
  3.4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the transparency burden. It clearly identifies the core action (send message) without stating side effects like the 4096-character limit (which is in the schema param but not the description) or delivery guarantees. It doesn't mention rate limits, auth requirements, or what happens on failure. For a straightforward messaging tool with no annotations, 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.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single concise sentence with zero waste. It's appropriately front-loaded with the primary action. While it could arguably add a bit more context, for a simple messaging tool, this brevity is appropriate and efficient.

  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?

  There's an output schema present, and all 5 parameters are documented with 100% schema coverage, so the structured data carries significant explanatory weight. The tool is relatively simple (send a message). However, the description doesn't address behavioral nuances like what happens with markdown parsing failures, the character limit, or when disable_web_page_preview matters. For a medium-complexity tool with good structured coverage, this is adequate but has room for richer guidance.

  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 the schema already documents every parameter thoroughly (text limit, target format, parse_mode options, reply_to, preview toggle). The description itself adds no parameter-level meaning beyond 'Send a text message.' Given the high schema coverage, the baseline 3 applies—the description doesn't need to repeat what the schema already covers.

  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 a specific verb+resource: 'Send a text message to a Telegram chat.' It clearly identifies what the tool does. However, it doesn't explicitly distinguish itself from siblings like send_photo or send_document, though the message-type distinction is implied by 'text message' and the overall toolset context.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies usage for sending text messages, and the schema makes the required parameters obvious. However, there's no explicit guidance about when to use this vs. edit_message_text, or when rich formatting (parse_mode) is appropriate. No exclusions or alternatives are named, leaving the agent to infer context.

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

• get_chatA
  3.6/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries full burden for behavioral disclosure. Since this is a read operation, a readOnlyHint annotation would be helpful, but its absence isn't the description's fault. The description notes it returns 'information', implying a read, but doesn't disclose details like what specific fields are returned or any auth requirements. No annotations to contradict, so baseline is maintained.

  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 that says exactly what's needed. Zero wasted words, fully front-loaded with the verb-resource pairing. Appropriate length for a single-parameter lookup 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?

  The tool has a simple single-parameter signature, full schema coverage, and an output schema (which presumably documents return values). For this level of complexity, the description is adequate. Complete guidance for a straightforward lookup. Could be slightly richer on what type of info is returned, but overall sufficient given the output schema exists.

  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 well-documented in the schema with examples of both username and numeric id formats. The description adds no additional parameter context beyond what the schema provides, so baseline 3 is appropriate since the 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 clearly states the verb ('Return information') and resource ('a chat'), and clarifies the scope by explicitly listing the covered types (group, channel, or private). It distinguishes itself reasonably from siblings like get_chat_member_count (which returns a count, not general info), though it doesn't explicitly differentiate from list_chats beyond implying a single-target lookup.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies a single-chat lookup use case but provides no explicit when-to-use versus alternative guidance. It doesn't mention that this is for fetching one chat's details as opposed to get_chat_member_count or list_chats. The usage context is inferable but not explicitly stated.

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

• get_meA
  4.2/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden. It discloses that the tool is read-only (returns information), non-mutating, and appears side-effect free (no destructive operations implied). While it doesn't detail authentication requirements or rate limits, the read-only nature and the 'etc.' acknowledging additional fields provide reasonable transparency for a getter.

  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 fully captures the tool's purpose with zero wasted words. It front-loads the primary function and lists the key returned fields. This is exemplary conciseness for a zero-parameter tool.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The tool has a trivial input surface (no parameters) and does have an output schema, so the description's job is minimal. It adequately conveys the return content. Slight deduction: with so little required context, the description could perhaps note the read-only guarantee explicitly, but given the output schema exists, completeness is strong.

  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 0 parameters, so there are no parameter semantics to describe. The baseline of 4 applies here since there are no parameters requiring documentation; the description correctly focuses on what the tool returns rather than input configuration.

  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 (return), the resource (basic information about the bot), and enumerates the specific fields (id, username, name, etc.). This unambiguously distinguishes it from sibling tools like get_chat and get_chat_member_count, which target other entities.

  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 bot identity/profile info, which is self-evident for a self-information tool. However, it does not explicitly state when to prefer this over get_chat (which might retrieve chat metadata), nor does it offer exclusionary guidance. For a zero-parameter self-inspection tool, the need for guidance is low, but there is no explicit context offered.

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

• list_chatsA
  4.4/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden. It discloses side effects (fetches new Telegram updates, saves chats to disk), caching behavior (subsequent calls return cached list plus new), and return structure (chats list with fields, hint key). This is strong behavioral disclosure, though it slightly understates the network I/O implication and doesn't mention 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.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Well-structured with headers (Persistent discovery, Static config) and a clear returns section. The content is dense but organized. Could arguably drop the 'hint' formatting line ('"Name=chat_id..."') to tighten, but the format example adds genuine value. Slightly verbose but every section 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 zero-parameter tool with an output schema, the description is remarkably complete. It documents both data sources, the caching/refresh behavior, the return structure with field names and types, the 'hint' semantics, and follow-up instructions. Given the tool's complexity (multi-source list with side effects), this is thorough and self-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 there is nothing for the schema to document. The description compensates by fully explaining the return dict structure (chats with fields, hint), which effectively serves as the parameter/output documentation. Baseline 4 is appropriate for a zero-param tool with a well-documented output.

  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 verb+resource ('List all known chats the bot can send messages to') and clearly distinguishes from siblings. It clarifies it returns chats usable with send_message and other tools, differentiating from get_chat/get_chat_member_count which operate on a specific chat. The scope ('known chats') is well defined.

  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 explains when to use this tool (to discover what chats the bot can message) and provides clear context for the two data sources (cached discovery + static config). It also gives guidance on what to do when a desired chat is missing (communicate hint, call again). However, it doesn't explicitly name alternative tools to use instead, though the sibling context makes this somewhat implicit.

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