Server Quality Checklist

Tool Scores

• telegram_list_mediaA
  4/5.0
  Behavior3/5

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

  Annotations already indicate read-only, non-destructive, idempotent, and closed-world behavior, covering safety and operational traits. The description adds useful context about the prerequisite ('Requires a previous telegram_sync_chat run'), which is not captured in annotations, but does not disclose other behavioral aspects like rate limits, error handling, or pagination. No contradiction with annotations exists.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose in the first sentence, followed by prerequisite and filtering details in a second sentence. Every sentence earns its place by providing essential information without redundancy, making it appropriately sized and well-structured.

  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 moderate complexity (list operation with filtering), rich annotations (covering safety and behavior), and 100% schema coverage, the description is mostly complete. It includes prerequisite context and filtering guidance. However, without an output schema, it does not describe return values (e.g., format of listed media), leaving a minor gap in 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?

  Schema description coverage is 100%, with clear descriptions for both parameters (chat_id and media_type with enum). The description adds minimal value beyond the schema by mentioning filtering by type, which is already detailed in the schema's enum and description. Baseline 3 is appropriate as the schema does the heavy lifting.

  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 ('List') and resource ('all media files that have been downloaded for a chat'), specifying the scope ('synced media' from a previous sync operation). It distinguishes from siblings like telegram_download_media (which downloads) and telegram_list_chats (which lists chats, not media), making the purpose specific and differentiated.

  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 it ('Requires a previous telegram_sync_chat run') and includes filtering options ('Filter by type'), which helps guide usage. However, it does not explicitly state when not to use it or name alternatives (e.g., telegram_get_history might overlap in some contexts), so it lacks full exclusion or comparative guidance.

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

• telegram_sync_chatA
  4.1/5.0
  Behavior4/5

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

  Annotations cover key traits (not read-only, open-world, idempotent, non-destructive), but the description adds valuable context beyond this: it explains the incremental sync behavior, local storage path ('data/raw/{chat_id}/'), and that it handles both messages and media. It doesn't mention rate limits or authentication needs, but provides useful operational details.

  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 appropriately sized and front-loaded, starting with the core functionality. Every sentence adds value: the first explains the action, the second covers incremental sync, the third specifies storage location, the fourth positions it among tools, and the fifth clarifies parameter usage. It could be slightly more concise by combining some points.

  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 complexity (sync operation with media handling), annotations provide good safety/behavioral coverage, and the description adds operational context. However, without an output schema, it doesn't describe return values or error conditions, which leaves a minor gap. Overall, it's mostly complete for effective use.

  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 both parameters well. The description adds some context by explaining the effect of omitting 'since_date' ('for full sync or incremental from last sync'), but doesn't provide additional syntax or format details beyond what the schema specifies. This meets the baseline for 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 clearly states the specific action ('downloads all messages and media files from a chat to local storage') and distinguishes it from siblings by emphasizing it's the 'main tool for extracting chat data including photos and documents.' It explicitly mentions what it does (full sync with incremental capability) and what resources it handles (messages, media files).

  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 it ('main tool for extracting chat data') and how to control sync behavior with 'since_date'. However, it doesn't explicitly state when to use alternatives like 'telegram_get_history' or 'telegram_download_media', which could help differentiate further among siblings.

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

• telegram_find_chatA
  4.2/5.0
  Behavior4/5

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

  The description adds valuable behavioral context beyond annotations: it specifies that the tool returns 'chat info or null if not found', which clarifies the response format and null handling. Annotations already cover safety (readOnlyHint=true, destructiveHint=false) and idempotency, so the description appropriately focuses on output behavior without contradiction.

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

  Conciseness5/5

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

  The description is two concise sentences that are front-loaded with the core functionality and follow with outcome details. Every word contributes to understanding the tool's purpose and behavior 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?

  Given the tool's low complexity (single parameter, no output schema), the description is mostly complete: it covers purpose, usage, and behavioral output. However, it lacks details on error cases or limitations (e.g., search scope or performance), which could enhance completeness for a search 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 description mentions the query parameter ('by name, username, or ID'), but the input schema already provides 100% coverage with a detailed description including examples. The description adds minimal semantic value beyond what's in the schema, meeting the baseline for 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 clearly states the specific action ('Search for a specific chat'), the resource ('chat'), and the search criteria ('by name, username, or ID'). It distinguishes from sibling tools like 'telegram_list_chats' (which lists all chats) by focusing on targeted search with a query parameter.

  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 searching for a specific chat by identifiers) but does not explicitly state when not to use it or name alternatives. For example, it doesn't clarify that 'telegram_list_chats' should be used for browsing all chats without a specific target.

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

• telegram_download_mediaA
  4.4/5.0
  Behavior4/5

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

  The description adds valuable behavioral context beyond what annotations provide: it specifies the return value ('Returns file path and metadata'), which isn't covered by annotations. The annotations already indicate it's not read-only, is open-world, idempotent, and non-destructive, so the description doesn't need to repeat those aspects but usefully complements them with output information.

  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 perfectly concise with two sentences that each serve a distinct purpose: the first states the core functionality and usage context, the second specifies the return value. There's no wasted language, and it's front-loaded with the primary action.

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

  Completeness4/5

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

  Given the tool's moderate complexity (3 parameters, no output schema), the description provides good contextual completeness by explaining the purpose, usage guidelines, and return values. The annotations cover safety and behavioral traits well, and while an output schema would be ideal, the description adequately compensates by specifying what's returned.

  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 100% schema description coverage, the input schema already fully documents all three parameters (chat_id, message_id, output_dir). The description doesn't add any additional parameter semantics beyond what's in the schema, so it meets the baseline expectation without providing extra value in this dimension.

  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 ('Download media from a specific message') and resource ('media'), distinguishing it from sibling tools like telegram_list_media (which lists) and telegram_sync_chat (which performs bulk operations). The phrase 'targeted downloads instead of a full sync' explicitly differentiates its purpose from alternatives.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool ('for targeted downloads') and when not to use it ('instead of a full sync'), directly referencing the sibling tool telegram_sync_chat as an alternative for bulk operations. This gives clear context for 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.

• telegram_get_historyA
  4.4/5.0
  Behavior4/5

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

  Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context about what data is returned (message text, sender, date, media info) and clarifies that media files are not downloaded, which is not captured in annotations. No contradictions with annotations.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose, followed by key behavioral details and usage guidance in three efficient sentences. Every sentence adds value without redundancy, making it highly concise and well-structured.

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

  Completeness4/5

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

  Given the annotations cover safety and idempotency, and the schema fully describes parameters, the description provides good contextual completeness by explaining the return data and usage context. However, without an output schema, it could briefly mention the response format more explicitly, though it's implied.

  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 fully documents all parameters. The description does not add any additional meaning or details about the parameters beyond what the schema provides, meeting the baseline expectation.

  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 ('Fetch messages') and resource ('from a Telegram chat'), and distinguishes it from sibling tools by explicitly mentioning what it does not do (download media files) and referencing telegram_sync_chat as an alternative for that purpose.

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

  Usage Guidelines5/5

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

  It provides explicit guidance on when to use this tool ('Useful for previewing chat contents before a full sync') and when not to use it ('Does NOT download media files — use telegram_sync_chat for that'), directly naming an alternative tool for related functionality.

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

• telegram_list_chatsA
  4.4/5.0
  Behavior4/5

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

  Annotations already provide comprehensive safety information (readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true). The description adds valuable context about what information is returned (chat ID, title, type, username) and the purpose of finding chat_id for other tools. It doesn't contradict annotations and provides useful behavioral context 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 perfectly concise with two sentences that each serve distinct purposes: the first explains what the tool does and what it returns, the second provides usage guidance. There's zero wasted language and it's front-loaded with the core functionality.

  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 listing tool with comprehensive annotations and a well-documented single parameter, the description provides excellent context about what's returned and when to use it. The only minor gap is the lack of output schema, but the description adequately describes the return format. It's nearly complete for this tool's 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 100%, so the schema already fully documents the single 'limit' parameter. The description doesn't add any parameter-specific information beyond what's in the schema. With complete schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but also doesn't need to.

  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 verb ('List') and resource ('Telegram dialogs (chats, groups, channels)'), and distinguishes this from siblings by specifying it returns chat ID, title, type, and username. It explicitly mentions this is for finding chat_id needed for other tools, which differentiates it from other list/search tools.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool ('Use this to find the chat_id needed for other tools'), which clearly distinguishes it from siblings like telegram_find_chat (likely for specific searches) and telegram_list_media (for media content). This gives the agent clear context about the primary use case.

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

• telegram_sync_statusA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds useful context about what data is returned (last sync date, total messages, last message ID), which isn't in the annotations, but doesn't mention rate limits, auth needs, or error conditions. With annotations providing core behavioral traits, this extra context warrants a score above 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 two sentences, front-loaded with the core purpose and followed by usage guidance. Every word adds value—no repetition or fluff—making it highly efficient and well-structured for quick 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?

  For a simple read-only tool with one parameter and no output schema, the description provides good context: it explains what the tool does, when to use it, and what data to expect. However, it doesn't detail the return format (e.g., JSON structure) or potential errors, leaving a minor gap given the lack of output schema.

  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, with the 'chat_id' parameter fully documented. The description doesn't add any parameter-specific details beyond what the schema provides, such as format examples or constraints. According to the rules, with high schema coverage, the baseline is 3 when no additional param info is given.

  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 ('Check the sync status') and resource ('for a chat'), listing the exact data returned (last sync date, total synced messages, last message ID). It distinguishes from siblings like 'telegram_sync_chat' (which performs a sync) by focusing on status retrieval rather than execution.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use this tool ('Useful before deciding whether to run a new sync'), providing clear context for its application. It implies an alternative (using 'telegram_sync_chat' for actual syncing) without naming it directly, but the guidance is specific and actionable.

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