Server Quality Checklist

Tool Scores

• mail_download_attachmentA
  3.5/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden and does meaningful work: it discloses the download destination (controlled directory), the returned metadata, and explicitly states that attachments are not parsed or executed. It does not cover authentication requirements, size limits, or failure modes, but the core safety and storage behavior is transparent.

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

  Conciseness5/5

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

  The description is two compact sentences with no filler. It front-loads the action and output, then adds the important safety caveats. Every clause earns its place.

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

  Completeness4/5

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

  For a simple three-parameter download tool with no output schema and no annotations, the description covers the key contract: what is downloaded, where it goes, what is returned, and what is not done. It is slightly incomplete regarding error behavior and how to obtain the required IDs, but these are minor gaps for this 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 0% description coverage and the description provides no additional meaning for account_id, message_id, or attachment_id. The agent must rely on parameter names alone; the description does not compensate for the missing parameter documentation.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states a specific action (download raw attachment) and resource (attachment on server), plus the output contract (path, size, SHA256). It distinguishes itself from siblings like mail_get_message and mail_export_message by emphasizing raw download and non-parsing/non-execution behavior.

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

  Usage Guidelines2/5

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

  The description does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions. The safety-related notes (no parsing/execution) imply a use case, but the tool never routes the agent to siblings like mail_export_message or mail_get_message for other scenarios.

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

• mail_export_messageA
  3.8/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses the local persistence behavior, the scope of exported content, per-attachment failure reporting, and the complete flag semantics. It does not mention authentication or side effects, but the core behavioral traits are clearly communicated.

  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 dense sentence, front-loading the action and resource, then using a semicolon to add result semantics. Every word contributes meaning; there is no filler or redundant restatement.

  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 core operation and result semantics are covered, but there is no output schema and the description omits parameter-level details and behavior when include_attachments is false. It is adequate for a simple tool but leaves meaningful gaps for an agent deciding exactly how to invoke it.

  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 account_id, message_id, or include_attachments. While the names are somewhat self-explanatory, the include_attachments flag's relationship to 'non-inline attachments' is not clarified, and the description does not compensate for the missing 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 '保存' (save), a clear resource (full body, metadata, non-inline attachments), and a clear target (本机/local machine). This distinguishes it from sibling tools like mail_get_message or mail_download_attachment, which read or download rather than export a complete message locally.

  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 save-to-local-machine behavior implies when to use it: when a complete message export is needed rather than just listing, reading, or downloading a single attachment. However, it does not explicitly mention alternatives or state when NOT to use it, leaving the routing decision mostly to inference.

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

• mail_get_messageA
  3.9/5.0
  Behavior3/5

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

  There are no annotations, so the description carries the behavioral burden. It discloses that overly long bodies come with a truncated marker, which is useful. However, it does not describe error behavior, authentication expectations, or whether both text and HTML bodies are always returned, so coverage 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?

  Two concise sentences with no filler. The primary return content is stated first, followed by truncation behavior and the export alternative. Every sentence adds value.

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

  Completeness4/5

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

  For a retrieval tool with no output schema and no annotations, the description covers the main return values, truncation behavior, and the relevant alternative for full export. It is slightly thin on how attachment IDs relate to mail_download_attachment, but the core calling context is present.

  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 account_id, message_id, or max_body_chars. The parameter names are somewhat self-explanatory and the truncated marker hints at max_body_chars, but the description does not compensate for the complete lack of schema-level descriptions.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the specific action: getting email text/HTML body and attachment IDs. It also differentiates from the sibling export tool by noting that full persistence is handled via export, so an agent can distinguish this from mail_export_message and mail_download_attachment.

  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 clear usage condition: if the full body needs to be saved to disk, call export instead. It does not explicitly mention when to use mail_download_attachment for attachment bytes, but the main routing decision between retrieval and export is well covered.

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

• mail_list_accountsA
  4/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the burden of behavioral transparency. The caveat about configured accounts not guaranteeing valid authorization is useful and non-obvious. Still, it does not mention read-only behavior, failure modes, or other side effects, though a listing action is inherently low-risk.

  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 with no filler. The caveat about authorization is valuable and earns its place, and the main purpose is front-loaded before the caveat.

  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 zero-parameter listing tool, the description is largely complete: it states what is listed and adds an important semantic caveat about authorization. It does not spell out the exact return format, but the absence of an output schema lowers the burden, and the tool's simple nature makes this gap minor.

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

  Parameters4/5

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

  The tool has zero parameters and schema coverage is complete, so there is little for the description to add. It appropriately names the primary output concepts (mailboxes and account_id), satisfying the baseline for a parameterless 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 uses a specific verb ('列出' / list) and a clear resource ('本地已配置邮箱及 account_id'), stating exactly what the tool returns. Its scope of local configured accounts distinguishes it from sibling tools that operate on messages rather than account enumeration.

  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 important context with the caveat that 'configured' does not imply currently valid authorization, which helps an agent interpret results. However, it does not explicitly state when to prefer this tool over alternatives or provide any exclusion criteria.

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

• mail_list_messagesA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the behavioral disclosure burden. It clearly discloses pagination behavior, the limit range (1-50), the use of next_cursor to continue, that it returns summaries only, and that it does not support full-text search. It does not mention auth, rate limits, or ordering, but these are less critical for a simple read listing.

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

  Conciseness5/5

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

  Two compact sentences deliver the core action, parameter constraints, pagination rule, and a key limitation with no filler. The main purpose is front-loaded and every phrase earns its place.

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

  Completeness4/5

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

  For a tool with three simple parameters, no output schema, and no annotations, the description covers the main invocation details: target account, list scope, pagination, and non-search behavior. It could mention how to obtain account_id or what summary fields are returned, but the existing description is sufficient for an agent to call the tool correctly in common cases.

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

  Parameters4/5

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

  Schema description coverage is 0%, so the description must compensate. It does: '指定邮箱' maps to account_id, 'limit 1-50' defines the limit parameter, and '使用返回的 next_cursor 继续' explains the cursor parameter. It omits the default limit of 10, but overall adds significant meaning beyond the bare schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific verb ('列出') and resource ('指定邮箱收件箱邮件摘要'), and adds pagination context. It is clearly distinct from sibling tools like mail_get_message, mail_download_attachment, and mail_export_message, since it lists summaries rather than retrieving, downloading, or exporting 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?

  The usage context is implied: use this to page through inbox message summaries. It explicitly notes the lack of full-text search, which helps rule out search requests, but it does not explicitly point to alternatives such as mail_get_message for full message content or mail_list_accounts for resolving account IDs.

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