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

Discloses key behaviors: mode options (send/draft/open), body_html fallback requirement, attachments as file paths, and from_address constraints. Lacks error handling or rate limit info, but given no annotations, this is adequate.

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

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

Description is long but well-structured with bullet-style parameter explanations. The purpose is front-loaded. Some redundancy could be trimmed, but the length is justified by 10 parameters.

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

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

Covers all parameters and basic return value, but lacks context on when to prefer sibling tools like create_rich_email_draft or prerequisites like account configuration. With output schema present, return details are acceptable.

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

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

Schema has 0% description coverage, but the description adds extensive meaning: examples for account, comma-separated for recipients, plain-text fallback, mode descriptions, file paths for attachments, and from_address must be configured.

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

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

Clearly states 'Compose and send a new email from a specific account.' This distinguishes it from sibling tools like forward_email or reply_to_email.

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

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

Provides no explicit guidance on when to use this tool versus alternatives such as create_rich_email_draft or manage_drafts. The mode parameter implies different uses but no direct comparisons.

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

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

With no annotations, the description must disclose behavior. It explains nesting creates intermediate segments if needed, but does not mention error handling for duplicate names, permissions, or scope of the operation.

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

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

Concise with clear structure: main purpose, nesting explanation, Args list, Returns. Minor redundancy in the nesting examples but overall well-organized and front-loaded.

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

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

Covers basic usage and returns confirmation path, but lacks details on error states, permission requirements, or behavior when mailbox name conflicts. Output schema is present but minimal; description could be more complete.

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

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

Schema description coverage is 0%, but the description explains each parameter: account (account name), name (can include slashes for nesting), parent_mailbox (optional existing folder). 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.

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

Clearly states 'Create a new mailbox (folder)' with specific verb and resource. Explains nested path creation via parent_mailbox or slash-separated name, differentiating it from sibling tools that list or manage emails.

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

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

Provides two alternative usage patterns for nesting (parent_mailbox vs. slash-separated name). Lacks explicit conditions for when not to use (e.g., if mailbox already exists) or comparison with sibling tools, but the given guidance is clear.

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

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

Even without annotations, the description thoroughly discloses behavioral traits: it generates an unsent .eml, optionally opens in Mail, handles fallback between text_body and html_body, and explains from_address requirements with default behavior. It also warns about the AppleScript limitation, adding transparency beyond the schema.

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

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

The description is well-structured with a clear summary, rationale, parameter list, and return info. It is comprehensive but slightly lengthy due to the 11 parameters. Every sentence adds value, making it efficient for its complexity; a 4 is appropriate for being thorough without excessive redundancy.

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

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

Given the tool's complexity (11 parameters, interdependencies, output schema), the description covers most aspects: fallback between text and HTML, from_address constraints, and Mail open/save behavior. However, it could clarify behavior when both bodies are omitted and the exact meaning of 'missing details' in the return. Still, it is largely complete.

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

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

With 0% schema coverage, the description fully compensates by explaining each of the 11 parameters in detail. It provides examples (e.g., account 'Work' or 'Oracle'), specifies defaults (e.g., subject defaults to empty), and clarifies conditional logic (e.g., fallback generation when one body is omitted). This adds significant meaning beyond the plain schema.

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

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

The description clearly states the tool creates a rich-text email draft by generating an unsent .eml file and optionally opening it in Mail. It distinguishes itself from alternatives like compose_email by noting that .eml is preferred for HTML emails due to reliable rendering, which prevents the AppleScript HTML injection issue.

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

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

The description provides strong usage guidance by stating it is the preferred path for HTML or richly formatted emails, implying a distinction from plain-text email tools. However, it does not explicitly name alternative sibling tools like compose_email for plain text, missing an opportunity for clearer when-to-use vs when-not-to-use.

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

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

With no annotations, the description carries full burden. It explains the scope options, default values, safety cap on max_emails, and return type. However, it does not mention authentication or whether the tool modifies any state.

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

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

The description is concise and well-structured, with a clear parameter list. Every sentence adds value; no wasted words.

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

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

Given the tool's complexity (7 parameters, output schema exists), the description covers all parameters and mentions the return type. It is complete for an export tool, addressing backup and analysis needs.

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

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

Schema description coverage is 0%, so the description must add meaning. It explains all 7 parameters, providing examples, defaults, roles, and constraints (e.g., subject_keyword required for single_email). This adds significant value beyond the schema.

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

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

The description clearly states 'Export emails to files for backup or analysis,' using a specific verb (export) and resource (emails to files). It distinguishes this tool from sibling tools like compose or search by focusing on file export.

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

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

The description provides parameter details that imply usage (e.g., single_email vs entire_mailbox), but does not explicitly state when to use this tool versus alternatives or when not to use it. There is no mention of sibling tools.

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

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

The description adds behavioral context for the 'from_address' parameter (must be configured address, defaults to account setting) and mentions a return confirmation. However, it does not disclose sending behavior (immediate or draft), nor any side effects like being non-destructive.

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

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

The description is front-loaded with a one-sentence purpose, followed by a structured Args list. It is adequately concise for 8 parameters, though the list is somewhat lengthy but necessary.

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

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

Given the tool has 8 parameters with 3 required, an output schema, and no annotations, the description covers all parameters and the return format. It is fairly complete for the complexity level, though lacks behavioral warnings.

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

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

Despite schema coverage being 0%, the description provides detailed explanations for all 8 parameters, including types (comma-separated), defaults, and constraints for 'from_address'. This adds significant value beyond the bare schema.

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

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

The description clearly states 'Forward an email to one or more recipients,' which is a specific verb+resource combination. However, it does not differentiate from siblings like 'compose_email' or 'reply_to_email' which are similar send actions.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., when to forward vs reply or compose). The description only lists parameters without contextual usage advice.

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

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

Discloses scanning the Sent mailbox and cross-referencing subject and recipient, but lacks details on edge cases (e.g., replies with different subjects), performance, or error behavior. Annotations are absent, so description carries full burden but is only moderately thorough.

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

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

The description is well-structured with a one-line summary, a paragraph explaining logic, and bullet-like Args/Returns sections. Every sentence is informative and concise.

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

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

The description covers the main behavior, parameters, and return format, and is sufficient for understanding tool use. However, it omits potential error conditions (e.g., invalid account) and does not leverage the output schema visibility (if any).

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

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

All four parameters are explained in the Args section (account, days_back, exclude_noreply, max_results) with clear defaults and purpose, compensating for the 0% schema coverage. The descriptions add meaningful context beyond the schema titles.

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

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

The description states 'Find sent emails that haven't received a reply yet' with specific verb and resource, and it distinguishes from tools like 'get_needs_response' by focusing on cross-referencing sent items with inbox replies.

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

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

The description implies usage for follow-up tracking but does not explicitly compare to siblings like 'get_needs_response' or state when not to use. No exclusions or alternative suggestions are provided.

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

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

No annotations provided, so description carries full burden; it discloses that thread identification uses subject similarity, returns sorted messages, and has a default max of 50, but does not mention permissions or potential side effects (though read-only).

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

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

Well-structured with Args and Returns sections; each sentence is informative and there is no redundant information.

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

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

Description covers purpose, inputs, and output format; with an output schema present and a clear description of the return, it is sufficiently complete, though missing error handling details.

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

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

Despite 0% schema description coverage, the description provides detailed explanations for all 4 parameters including examples, defaults, and usage context, adding significant value beyond the schema.

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

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

Description clearly states it gets an email conversation thread by grouping messages with same or similar subject, which distinguishes it from siblings like search_emails or list_inbox_emails.

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

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

Description explains when to use (to retrieve a thread) and what inputs are needed, but does not explicitly mention when not to use or suggest alternatives.

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

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

With no annotations, the description carries full burden. It discloses output structure and AI suggestion capability, but lacks information on performance, rate limits, or auth requirements. Being a read-only tool, the disclosure is adequate but not exhaustive.

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

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

The description is concise and front-loaded with purpose, followed by a bullet-like list of outputs. Every sentence adds value without redundancy.

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

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

Given no parameters and the presence of an output schema (context signal), the description fully covers what the tool does and returns, making it complete for an agent to decide when to use it.

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

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

The tool has zero parameters, so no parameter explanation is needed. The description compensates by detailing the return values, which adds value beyond the empty input schema.

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

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

The description clearly states the tool provides a comprehensive overview of inbox status across all accounts, listing specific outputs like unread counts, mailboxes, and AI suggestions. This distinguishes it from siblings like get_mailbox_unread_counts or get_needs_response.

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

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

The description implies using this tool for a high-level inbox overview with AI-driven action suggestions. It does not explicitly exclude alternatives or provide when-not-to-use guidance, leaving some ambiguity.

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

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

The description explains the return structure and behavior of the summary_only flag, but without annotations, it fails to mention that this is a read-only operation, any idempotency, or potential 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.

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

The description is brief and well-structured with Args/Returns sections. Every sentence adds value, and there is no redundancy.

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

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

Given the moderate complexity (3 optional params, no required) and presence of output schema, the description covers the core behavior and return types. Missing details like error handling or account name format, but adequate for a simple read tool.

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

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

With 0% schema description coverage, the description compensates well by explaining each parameter's purpose (account as filter, include_zero for zero-count inclusion, summary_only for aggregation). It adds context beyond the schema's type and default.

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

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

The description clearly states the tool gets unread counts per mailbox, with optional account filtering and summary mode. It distinguishes itself by mentioning it replaces the former get_unread_count tool.

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

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

It provides context for when to use summary_only mode but does not explain when to use this tool over siblings like get_inbox_overview or get_statistics. No explicit exclusions or alternatives are given.

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

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

With no annotations, the description provides substantial behavioral details: it filters out newsletters and automated emails, prioritizes direct emails with question marks, and returns a ranked list with priority hints. This adequately informs the agent about the tool's behavior, though it does not explicitly state read-only nature.

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

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

The description is concise and well-structured: a brief purpose paragraph followed by a clear Args listing. No superfluous information, though the purpose statement could be slightly more front-loaded.

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

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

Given the presence of an output schema (not shown but referenced), the description appropriately summarizes the return type. It covers the filtering logic and all parameters. Minor gap: no mention of whether emails are marked as read, but overall sufficient for a retrieval tool.

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

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

The input schema has 0% description coverage, but the description compensates fully with a clear 'Args' section explaining each parameter's purpose and defaults (e.g., account as the email account name, mailbox defaulting to 'INBOX'). This adds significant meaning beyond the schema structure.

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

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

The description clearly states the tool's purpose: identifying unread emails that likely need a response. It specifies filtering and prioritization criteria, making the action clear. However, it does not differentiate from sibling tools like 'get_awaiting_reply', which may have overlapping functionality.

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

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

The description implies when to use (when you need to find actionable emails), but it lacks explicit guidance on when not to use this tool or which alternatives to consider. No mention of siblings or exclusions, 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.

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

No annotations are provided, so the description must disclose behavioral traits. It explains parameters and return type, but lacks details on side effects (none expected), rate limits, or data freshness. The 'get' verb implies read-only, but it is not explicit.

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

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

Well-structured with a clear intro, Args list, and Returns line. It is not overly verbose, though the Returns line may be redundant given the output schema. Could be slightly more concise.

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

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

Coverage of parameters is good, but missing broader context like prerequisites (e.g., account must be set up), data latency, or potential performance impact. The output schema likely fills return structure details, but behavioral context is lacking.

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

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

The description provides detailed explanations for all 5 parameters in the Args section, including examples (e.g., account names, scope options). The input schema has no descriptions (0% coverage), so the description fully compensates.

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

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

The description states 'Get comprehensive email statistics and analytics,' which clearly indicates the verb and resource. However, it does not explicitly differentiate from sibling tools like get_inbox_overview or get_top_senders, which are more specific.

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

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. The scope parameter hints at use cases, but there is no explicit when-to-use or when-not-to-use information.

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

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

No annotations are provided, so the description carries full burden. It describes the tool's behavior (analysis, ranking, grouping) and parameter effects (defaults, grouping). No side effects are noted, but none are expected for a read-only analysis tool.

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

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

The description is concise, well-structured with a purpose sentence, bulleted use cases, and a parameter list. Every part adds value without redundancy.

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

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

The description covers all necessary aspects: purpose, parameters, return value (ranked list with counts). It is complete for the tool's complexity, especially given the presence of an output schema.

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

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

With 0% schema description coverage, the description compensates by providing clear explanations for each parameter (account, mailbox, days_back, top_n, group_by_domain) with defaults and intended use, adding significant meaning beyond the schema.

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

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

The description clearly states the tool's action: 'Analyse a mailbox to find the most frequent senders.' It provides specific use cases (identifying key contacts, high-volume senders, newsletter sources) and distinguishes itself from sibling tools by focusing on sender frequency analysis.

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

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

The description includes explicit use cases ('Useful for...'), guiding when to use the tool. However, it lacks explicit when-not-to-use guidance or direct comparisons to alternative sibling tools, though the unique purpose is clear.

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

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

No annotations provided, so description carries the burden. Clearly states it returns a UIResource with an interactive HTML dashboard, and that it's read-only (no side effects mentioned). Also notes the dependency on mcp-ui-server. Could explicitly confirm non-destructive behavior, but is sufficient.

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

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

Concise and well-structured: opening sentence, bulleted list of features, note about requirements, and a clear return description. Every sentence adds information, no redundancy.

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

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

For a tool with no parameters and no output schema, the description explains the interactive UI, its components, and the required client support. Could address error handling or what happens if UI is unavailable, but returns an error message as noted. Adequate for context.

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

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

No parameters exist; schema coverage is 100%. Description adds value by explaining what the tool does without needing to clarify parameters. Baseline 4 is appropriate.

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

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

Description clearly states it 'Get an interactive dashboard view of your email inbox' and enumerates specific UI components (unread counts, recent emails, quick actions). Distinguishes from data-retrieving siblings like list_inbox_emails by emphasizing the interactive UIResource nature.

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

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

Describes the tool's purpose as providing an interactive UI dashboard, implying it should be used when a visual/actionable interface is desired over raw data. Notes that a compatible MCP client is required, giving a precondition. Does not explicitly contrast with alternatives, but context from siblings provides some differentiation.

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

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

With no annotations provided, the description carries the full burden. It clearly states the return format (dict mapping account name to list of addresses, with accounts having no addresses mapping to []). While it implies a read-only operation, it could explicitly note the lack of side effects or auth requirements.

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

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

The description is concise at 3 paragraphs: purpose, use case, return format. No redundant information, and sentences are well-structured and front-loaded.

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

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

Given the simplicity (no parameters, output schema exists, many siblings), the description covers the necessary aspects. It could be slightly more complete by specifying whether it lists all accounts or only configured ones, but it is sufficient for its intended use.

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

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

There are no parameters, so schema coverage is 100%. The description adds no parameter-specific information, but the baseline for 0 parameters is 4. It does provide context about the output, which indirectly helps understand the tool's usage.

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

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

The description explicitly states the verb 'list' and the resource 'configured email addresses for each Mail account'. It distinguishes itself from sibling tools like list_accounts by specifying the mapping from account name to addresses, and provides a concrete use case.

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

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

The description gives a specific scenario ('handy when an integration needs to know which inbox a message landed in by address rather than by Mail.app's display name'), which helps the agent decide when to use it. However, it does not explicitly state when not to use or mention alternatives.

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

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

Description implies a non-destructive read operation, but does not explicitly state behavioral traits like read-only or absence of side effects; annotations are absent, so description carries burden but 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.

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

Extremely concise with two sentences, front-loading the purpose and return value with no wasted words.

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

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

Description adequately covers purpose and return value for a simple list tool; could be slightly more explicit about scope (e.g., 'all accounts associated with the user'), but sufficient.

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

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

No parameters exist, so schema coverage is 100% trivially; baseline for 0 params is 4, and description adds no further parameter semantics, which is acceptable.

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

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

Description clearly states 'List all available Mail accounts' with a specific verb and resource, and it distinguishes itself from sibling tools like list_account_addresses and list_mailboxes by focusing on accounts.

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

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

No guidance on when to use or not use this tool compared to alternatives; no mention of prerequisites or context.

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

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

Without annotations, the description partially carries the burden. It states it lists attachments and checks up to 'max_results' emails, but does not disclose whether it modifies data, requires specific permissions, or searches all mailboxes versus inbox. The read-only nature is implied but not explicit.

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

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

The description is concise and front-loaded with purpose. The 'Args:' section is structured but somewhat redundant with the schema; however, it provides examples. Every sentence contributes, though some verbosity exists.

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

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

With three parameters, no annotations, and an output schema (not shown), the description covers the main functionality and return value. It could mention limitations like only checking first matching emails, but remains adequate for a relatively simple tool.

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

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

Schema description coverage is 0%, so the description adds essential meaning. It explains 'account' with examples, 'subject_keyword' as keyword search, and 'max_results' with default behavior. This adds value beyond the raw schema.

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

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

The description clearly states 'List attachments for emails matching a subject keyword,' specifying the verb (list) and resource (attachments) with a clear condition. It distinguishes itself from sibling tools like 'save_email_attachment' which has a different purpose.

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

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

The description implies usage for retrieving attachment details based on subject keyword, but lacks explicit guidance on when to use this tool versus alternatives like 'save_email_attachment' or 'search_emails'. No when-not-to-use or prerequisite information is provided.

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

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

No annotations provided, but description discloses that include_content makes it slower, account=None shows all accounts, and returns formatted list. Good transparency for a read tool.

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

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

Well-structured with Args and Returns sections. Could be slightly more concise by integrating the replacement note, but overall efficient and front-loaded with purpose.

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

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

Given output schema exists, description covers return format, all parameters, behavioral notes, and usage hints. Comprehensive for a list tool.

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

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

Schema coverage is 0%, but description fully explains each parameter: account filtering, max_emails=0 meaning all, include_read default, include_content being slower, output_format options. Adds significant value beyond schema.

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

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

Clearly states 'List all emails from inbox across all accounts or a specific account.' Uses specific verb and resource, distinguishes from sibling by noting replacement of get_recent_emails and optional filters.

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

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

Provides guidance on using account and max_emails for recent emails from single account. Doesn't explicitly compare to other list/search tools, but context is clear.

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

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 behavior such as optional account filtering, default include_counts=True, and return format details including nested mailbox representation. However, it does not mention permissions or side effects, which is acceptable for a read operation.

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

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

The description is brief yet complete, using a clear Args/Returns structure without any unnecessary words. Every sentence adds value.

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

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

All parameters are explained, the return format is described, and the tool's purpose is fully covered. No gaps remain despite lack of annotations.

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

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

With 0% schema coverage, the description fully explains both parameters: account as optional filter, include_counts as boolean with default True. This adds significant meaning beyond the schema's minimal titles.

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

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

The description clearly states the tool lists mailboxes (folders) for a specific account or all accounts, distinguishing it from sibling tools like list_accounts or list_inbox_emails by explicitly naming the resource 'mailboxes'.

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

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

The description explains when to use the tool (list mailboxes) and how the account parameter filters, but it does not explicitly state when not to use it or mention alternatives like get_mailbox_unread_counts for count-only needs.

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

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

No annotations provided, so description must compensate. It explains actions but omits side effects (e.g., 'send' will actually transmit email), auth requirements, rate limits, or error conditions. 'Returns: Formatted output based on action' is vague.

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

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

Description is well-structured with bullet points for arguments. Front-loaded with purpose and action list. Each sentence adds value, though could trim the 'Args' list slightly without losing clarity.

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

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

Tool is complex (9 params, 5 actions). Description covers parameter roles but lacks specifics: e.g., 'list' output format, 'open' behavior, or error handling. Output schema exists but description doesn't reference it. Some gaps remain.

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

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

Schema description coverage is 0%, forcing description to explain all 9 parameters. It adds meaning beyond schema: required fields for actions (subject, to, body for create), comma-separated recipients, and details on from_address including default behavior.

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

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

Description clearly states it manages draft emails and enumerates specific actions (list, create, send, open, delete). The verb 'manage' combined with resource 'drafts' and explicit action list leaves no ambiguity about scope.

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

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

No explicit guidance on when to use this tool versus siblings like compose_email or create_rich_email_draft. The description implies usage for draft operations but doesn't offer alternative recommendations or exclusions.

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

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

Since no annotations are provided, the description fully shoulders behavioral disclosure. It details dry run previews, safety limits, required confirmations, and filters. However, it does not mention reversibility of actions (e.g., whether permanent deletion is irreversible).

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

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

The description is logically structured with a brief overview followed by a parameter list. While it is somewhat lengthy due to 11 parameters, it avoids redundancy and each sentence adds value. Could be slightly more concise, but the length is warranted.

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

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

Given the tool complexity (11 parameters, no annotations, output schema present), the description fully covers usage, safety, and edge cases. It explains actions, filters, and safety flags. The return value is mentioned as a confirmation message, which is sufficient when an output schema exists.

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

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 all 11 parameters. It does so thoroughly: each parameter is described with default values, usage notes (e.g., subject_keywords matches any, not used for empty_trash), and safety constraints (e.g., max_deletes default 5). This adds significant meaning beyond the schema.

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

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

The description clearly states it manages trash operations (delete emails or empty trash), which is distinct from all sibling tools. No other tool handles trash management, 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.

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

The description explains when to use dry_run vs actual deletion, safety confirmations like confirm_empty, and filtering parameters. It lacks explicit 'when not to use' but the context is clear given the action-focused behavior.

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

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

Discloses key behaviors like dry_run preview, only_read skipping unread, and message_ids overriding filters. Mentions a safety limit (max_moves=50). However, with no annotations, it lacks details on irreversibility, permissions, or error states that a mutation tool should declare.

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

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

Front-loaded with a one-line purpose, followed by useful usage tips and a well-organized parameter list. Slightly long but every part adds value, with no wasted sentences.

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

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

Given 11 parameters and no annotations, the description covers most aspects: filtering, preview, archiving, exact IDs. Mentions return value briefly. Lacks clarification on overlap between subject_keyword and subject_keywords, but otherwise complete.

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

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

Schema coverage is 0%, so description fully documents all 11 parameters. The Args section adds clear purpose, defaults, and usage examples (e.g., nested mailboxes with '/'), going well beyond schema names and types.

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

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

The description clearly states 'Move email(s) matching filters from one mailbox to another', using specific verbs and resources. It distinguishes from siblings by mentioning a special path similar to update_email_status and providing archiving guidance.

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

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

Provides usage tips (dry_run, only_read, archiving) and explains message_ids for precise targeting. However, it does not explicitly state when to use this tool versus siblings like search_emails or export_emails, nor does it list exclusions or prerequisites.

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

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

Despite no annotations, the description details key behaviors: mode overrides send parameter, reply_to_all toggles recipients, body_html allows rich formatting requiring fallback text, and from_address specifies sender selection. It also notes the return of a confirmation message. This sufficiently covers behavioral traits.

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

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

The description is structured as a clear bulleted list with parameter descriptions, making it easy to scan. While it is lengthy due to many parameters, each sentence serves a purpose. A slight reduction in verbosity could improve conciseness.

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

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

The description covers all parameters and return value (confirmation message), given the presence of an output schema. It lacks explicit mention of error conditions or prerequisites (e.g., account validity), but for a straightforward reply tool, it is sufficiently complete.

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

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

Schema description coverage is 0%, but the description provides thorough explanations for all 11 parameters in the Args section, adding meaning to names like 'cc', 'bcc', 'attachments', and clarifying default values and interactions (e.g., mode overrides send). This fully compensates for the schema gaps.

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

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

The description clearly states 'Reply to an email matching a subject keyword,' which specifies the action (reply), resource (email), and selection method (subject keyword). This distinguishes it from siblings like 'compose_email' (create new) and 'forward_email' (forward).

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

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

The description implicitly indicates when to use this tool (to reply to an identified email), but it doesn't explicitly state when not to use it or suggest alternatives like 'compose_email' for new messages. Given many siblings, clearer guidance would improve this.

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

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

No annotations are provided, and the description does not disclose behavioral traits such as error handling (e.g., if attachment is not found), permission requirements, whether files are overwritten, or the search mechanism for subject_keyword. This is insufficient for a mutation action.

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

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

The description is brief and well-structured: a concise purpose sentence followed by a labeled bullet list of arguments and a return statement. Every sentence is useful, with no filler.

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

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

The description covers purpose, parameters, and return value, which is adequate for a tool with 4 required string parameters and an output schema. However, it lacks details on error behavior, search matching logic, and prerequisites (e.g., account must be synchronized), leaving gaps for the agent.

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

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

With 0% schema description coverage, the description compensates by providing a clear one-line explanation for each parameter (e.g., 'Account name (e.g., "Gmail", "Work", "Personal")'). This adds meaning beyond the schema's type and title.

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

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

The description clearly states 'Save a specific attachment from an email to disk,' specifying the verb (save), resource (attachment from email), and destination (to disk). It distinguishes from sibling tools like list_email_attachments, which only list attachments.

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

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 list_email_attachments or other email manipulation tools. The description only lists parameters 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.

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

Since no annotations are provided, the description carries the full burden. It discloses performance traits (body_text slower, account=None slower), pagination via offset/limit, and output format options. It does not mention authentication, rate limits, or read-only nature, but as a search tool those are less critical. The warnings are valuable.

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

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

The description is well-structured with a summary line followed by a detailed parameter list. It is verbose due to the many parameters, but each line is necessary. The front-loaded summary quickly communicates the tool's purpose. Could be slightly more concise, but overall effective.

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

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

Given the tool's complexity (19 parameters, many optional filters) and the existence of an output schema, the description covers everything needed: what the tool does, how to use parameters, performance implications, and return types. It is comprehensive and leaves little ambiguity for an AI agent.

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

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

With 0% schema description coverage, the description fully compensates. Every parameter is documented with purpose, default, and sometimes special values (e.g., mailbox: 'INBOX', 'All'; flag_color lists colors). This exceeds the baseline and provides rich context beyond the schema's property titles.

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

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

The description clearly identifies the tool as a unified email search tool, consolidating subject, sender, body, and cross-account searches. It distinguishes itself from siblings like list_inbox_emails by emphasizing filtering capabilities and advanced search features.

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

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

The description provides some usage guidance (e.g., warning that body_text is slower, account=None searches all accounts), but it does not explicitly tell when to use this tool versus alternatives like list_inbox_emails or get_email_thread. The context is implied but not direct.

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

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

With no annotations, the description discloses that sync is potentially long-running, uses a timeout for fire-and-forget semantics, and explains the implementation detail about synchronize vs check for new mail. It does not mention network activity or UI impact, but overall 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.

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

The description is well-structured with distinct sections but slightly verbose; still every sentence serves a purpose and it front-loads the core purpose.

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

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

Given one parameter, no annotations, and the presence of an output schema (stated but not shown), the description adequately covers return value and usage context within the sibling tools suite.

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

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

The only parameter 'account' is explained: account name (e.g., 'Gmail', 'Work') and that omitting it syncs every account, which adds meaning beyond the schema's anyOf/null/default.

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

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

The description clearly states the tool forces Mail.app to synchronize an account with the server immediately, distinguishing it from related operations like move_email and check for new mail by explaining the AppleScript verb difference and use cases.

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

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

Explicitly advises to use after move_email, update_email_status, or manage_trash for immediate push to downstream clients, and contrasts with the passive check for new mail, providing clear when-to-use guidance.

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

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

With no annotations, the description fully carries the burden. It explains critical behaviors: exact ID matching vs. filtering, apply_to_all requirement, flag_color re-coloring, and the max_updates safety limit. This provides a complete picture of the tool's actions.

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

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

The description is well-structured with a summary line, behavioral notes, Args list, and returns section. It is not overly verbose for 11 parameters, but could be slightly more concise without losing clarity.

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

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

Given the complexity (11 params, no annotations, output schema exists), the description covers all necessary aspects: parameter semantics, interactions, safety limits, and return values. It is complete and ready for an AI agent to use.

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

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 so thoroughly with a detailed Args list explaining each parameter, including action options, flag_color values and behavior, and the interaction between parameters. This adds substantial meaning beyond the schema.

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

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

The description clearly states the tool's function: 'Update email status - mark as read/unread or flag/unflag emails.' This is a specific verb+resource combination that distinguishes it from sibling tools like move_email or reply_to_email.

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

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. It provides interaction guidelines (e.g., message_ids overrides other filters) but lacks direct comparison with sibling tools like search_emails or move_email.

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