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

Describes soft-delete vs expunge, the irreversibility of permanent deletion, confirm requirement, and dryRun behavior. Annotations already mark destructiveHint=true; description adds critical context like lag in match searches and that permanent deletion is irreversible with no Trash recovery.

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 a single compact paragraph, front-loading the core purpose and then methodically covering conditions. Every sentence adds value without redundancy. Could be structured as bullet points but current form is efficient and clear.

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 output schema but 6 parameters with nested objects, the description covers all essential behavioral aspects: deletion methods, permanence, confirmation, dry-run preview, and safety warnings (content lag). An agent has complete information to invoke correctly.

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?

Input schema has 100% coverage, but description adds significant meaning: mutual exclusivity of uids/match, safety trade-offs, the need for confirm when permanent, and dryRun usage. This provides actionable guidance beyond enum values or basic 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 'Delete multiple messages in one operation' and specifies the two mutually exclusive inputs (uids or match), default soft-delete behavior, and permanent deletion conditions. This distinguishes it from single-message delete tools and other bulk operations.

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?

Explicit guidance: 'Provide EITHER uids OR match.' Further explains that explicit UIDs are safer for destructive cleanup due to content match lag, and dryRun previews without deletion. Also requires confirm: true for permanent deletion, providing clear when-to-use and safety constraints.

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?

Beyond annotations (destructiveHint, idempotentHint), the description warns that moved messages get new UIDs in the destination and explains dryRun behavior. No contradiction with annotations.

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

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

Two sentences, each essential, front-loaded with purpose, no filler. Well-structured for quick comprehension.

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 output schema and moderate complexity (5 params, nested objects), the description covers key aspects: parameter mutual exclusivity, dryRun, and UID renumbering. Lacks output return info, but is still fairly 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 100%, so baseline is 3. Description adds value by clarifying the mutual exclusivity of uids and match, and explaining dryRun effect, which goes beyond the schema descriptions.

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 multiple messages to a different folder,' specifying the verb and resource. It distinguishes itself from siblings like move_message and move_thread by indicating batch operation, and mentions the two mutually exclusive parameter options.

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 explains when to use uids vs match, and introduces dryRun for preview. However, it does not provide guidance on when to prefer this tool over alternatives like bulk_delete or move_message, 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?

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds that it's a bulk operation and references the flag whitelist, but does not cover transactional behavior, partial failures, or rate limits. Given annotation coverage, this is adequate but not exceptional.

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 extremely concise: two sentences with no redundant words. It front-loads the core purpose and follows with essential usage constraints. Every sentence carries weight.

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?

While the description covers the main points for a bulk flag operation, it lacks details on return value, error handling, behavior for empty selections, or atomicity. Given the complexity (6 params, nested object) and absence of output schema, more completeness would be helpful.

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 100% with detailed descriptions for each parameter. The description adds no new parameter information beyond summarizing the requirement. Baseline 3 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?

The description clearly states the verb 'add or remove flags' on 'multiple messages in one operation', effectively distinguishing it from the single-message sibling 'update_message_flags'. It also specifies the required inputs and mutual exclusivity.

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 explicit instructions on how to provide inputs (EITHER uids OR match, plus at least one flag operation). It references the flag whitelist from update_message_flags. However, it lacks explicit guidance on when to use this tool over alternatives like bulk_update_labels.

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?

Annotations indicate non-read-only, non-destructive, idempotent. The description adds behavioral context: label paths must start with 'Labels/', dryRun allows safe preview, and removing a label not on a message is a silent no-op (from labelsToRemove description). This adds value beyond annotations.

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

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

The main description is two sentences, extremely concise and front-loaded. It states the purpose first, then constraints. There is no wasted text, and every sentence earns its place.

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 (6 parameters, nested match object, XOR requirement), the description covers the essentials: what it does, constraints, safety preview, and reference to sibling tool for label-path rules. No output schema is present, but the return value is implied for dryRun. Missing error scenarios, but not critical.

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 100%. The description summarizes the mutual exclusivity and minimum requirements, and each parameter field has detailed descriptions that add meaning beyond the schema (e.g., folder 'Messages stay here; labels are additive', match conditions, labelsToAdd requirement to exist, labelsToRemove silent no-op, dryRun preview). The description effectively compensates for any complexity.

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 operation: 'Add or remove Proton labels on many messages in one operation.' It specifies the verb (add/remove), the resource (labels on messages), and the scope (bulk). This distinguishes it from siblings like update_message_labels (single message) and bulk_update_flags (different operation).

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 explicit usage guidance: 'Provide EITHER `uids` OR `match` (XOR), plus at least one of `labelsToAdd` / `labelsToRemove`.' It also references sibling tool `update_message_labels` for label-path rules and suggests `dryRun: true` for safe preview. While not explicitly stating when NOT to use it, the context is clear enough.

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?

Annotations already indicate read-only and idempotent behavior. The description adds that it returns just a number, attachment filters are rejected, and non-selectable namespace containers yield an actionable error. No contradictions.

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?

Three sentences, each adding value: purpose, behavior, and specific constraints. Front-loaded with main action. 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?

For a simple counting tool with no output schema, the description covers its main purpose, error handling, and limitations. No gaps given the complexity.

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 schema has 100% description coverage. The description adds context: attachment filters are rejected due to performance trade-offs, and omitting match counts all messages. This goes 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 that the tool counts messages in a folder with optional search criteria and returns only a number. It distinguishes itself from search_messages by explicitly noting attachment filters are not allowed, clarifying its 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 provides explicit guidance: use this tool for fast counts without fetching envelopes; avoid for attachment-based filtering, where search_messages is recommended. This helps the agent choose correctly.

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?

Beyond annotations (idempotentHint=true), the description reveals that the tool gracefully handles existing folders and that root-level paths trigger an actionable error. This adds valuable behavioral context.

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

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

Three sentences, each adding unique value: purpose, idempotency, and a usage constraint. No redundancy or unnecessary detail.

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 adequately covers what the tool does, its idempotent behavior, and a key failure scenario. It does not describe the return format, but for a tool without an output schema, the information provided is sufficient for correct usage.

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 schema already describes the 'path' parameter in detail with examples. The description reiterates the prefix requirement but adds no new semantic information about the parameter itself, so baseline 3 applies.

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 action 'Create a new mailbox folder' and distinguishes it from sibling tools like 'create_label' by specifying it creates folders. The Proton-specific namespace requirement provides additional precision.

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 this tool (to create a folder) and provides important usage constraints (Proton 'Folders/' prefix, idempotent behavior). However, it does not explicitly contrast with alternative tools like 'rename_folder' or 'delete_folder'.

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?

Annotations already indicate idempotentHint=true, but description adds critical behavioral details: automatic namespace prepending, non-exclusive nature of labels, and silent success on duplicates. No contradictions.

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?

Three sentences, front-loaded with purpose, each sentence serves a distinct purpose (what, how, idempotency). 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?

No output schema, but description fully explains behavior, including namespace handling, label semantics, and idempotency. Sufficient for an agent to use correctly.

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

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

Schema covers the single parameter 'name' with clear description. The description reinforces the bare name requirement and explains the internal transformation, adding 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 'Create a new Proton label' with specific verb and resource. Distinguishes from sibling tools like create_folder and update_message_labels by explaining labels are non-exclusive tags.

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 instructs to pass bare label name without prefix, explains namespace prepending, labels' non-exclusivity, and directs to update_message_labels for applying/removing labels. Also notes idempotency for duplicate attempts.

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?

Annotations already indicate non-destructive and idempotent behavior. The description adds critical detail: deleting a folder moves contents to All Mail, deleting a label only removes the tag. This goes beyond annotations.

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

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

The description is well-structured with a clear first sentence stating purpose, followed by necessary constraints and behavioral details. 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?

For a one-parameter tool with no output schema, the description covers purpose, constraints, behavior, and edge cases (accepting . and .. for cleanup). No gaps identified.

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 schema already documents the path parameter with 100% coverage. The description adds examples and re-emphasizes the namespace constraint, adding 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 the action (delete) and the resource (mailbox folder or label container). It distinguishes from sibling tools like delete_message by specifying scope (Folders/ and Labels/ namespaces).

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 explicitly restricts usage to two namespaces, protecting system mailboxes, and notes that no confirm flag is required. It does not explicitly compare to alternatives but provides context for appropriate 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?

Annotations mark destructiveHint=true; the description adds nuance by explaining the move-to-Trash default, the permanent expunge option, and the UID renumbering caveat. This goes beyond bare annotations.

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?

Two sentences with critical information front-loaded; every sentence is essential. The caveat is placed after the core behavior, maintaining 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?

With 3 parameters and no output schema, the description sufficiently covers behavior, default, and the critical UID renumbering detail. No missing information for safe usage.

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 100%, but the description adds value by explaining the effect of 'permanent' (default false) and the UID-folder pairing caveat, which is not in 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 verb 'Delete' and the resource 'email message', and distinguishes between default move-to-Trash and permanent delete. This differentiates it from siblings like 'delete_thread' and 'bulk_delete'.

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 the default safe behavior and when to use permanent=true, but does not explicitly contrast with alternatives like 'move_message' to Trash or warn against misuse. The UID caveat provides important contextual 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?

Annotations already mark destructiveHint=true. Description adds essential details: default soft-delete to Trash, permanent expunge irreversibility, folder-scoping safety defaults, and dry-run preview. This goes well beyond the annotation and fully discloses 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?

Two concise sentences front-load the core action and immediately provide key behavioral nuances. Every sentence adds value with 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 destructive thread operation, description covers behavior, scope, preview, and safety defaults. No output schema needed; return values are implied. Complete enough for an agent to invoke correctly.

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

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

Input schema covers all 4 parameters with descriptions (100% coverage). The description adds minimal extra meaning beyond schema (e.g., 'for safety', 'previews'), but baseline is 3 due to high schema coverage. No new constraints or clarifications added.

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 deletes every message in a thread (specific verb+resource). It distinguishes from siblings like delete_message (single message) and bulk_delete (multiple arbitrary messages) by focusing on thread-level deletion.

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 provides clear context on default behavior (soft-delete), irreversible option (permanent), scope control (acrossFolders), and preview mode (dryRun). Although not explicitly stating when to use vs alternatives, the parameter guidance strongly implies proper usage scenarios.

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 side effects: file write only when saveTo provided, otherwise read-only. Explains idempotency and security checks. Aligns with annotations and adds context.

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. Front-loaded action, then prerequisites, then behavior details. No superfluous 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?

Covers all aspects: two modes, prerequisites, security, idempotency, and no output schema needed.

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?

Input schema covers all params with descriptions. Description adds important context: saveTo triggers file write, security constraints, and inline 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?

Clear verb 'Download' and specific resource 'email attachment by part number'. Distinguishes from siblings like list_attachments and read_message.

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 states to use read_message or list_attachments first to get part numbers. Explains two modes (inline vs saveTo) and when each applies. No explicit exclusions but strong 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?

Annotations already provide readOnlyHint=false and idempotentHint=true. Description adds useful behavioral details: default values for acrossFolders and dryRun, and preview behavior. No contradictions.

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?

Three sentences, no wasted words. Front-loaded with purpose, then usage guidance, then defaults/constraints.

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 when to use, precondition, and behavioral defaults. However, missing return value information (e.g., what the tool outputs), which is relevant since no output schema is provided.

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 covers all parameters with descriptions (100% coverage), so baseline is 3. Description adds some extra context like the non-empty constraint and default values but does not significantly augment 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?

Description clearly states the tool operates on a thread by Message-ID, distinguishing it from sibling tools like update_message_flags (single message) and bulk_update_flags (flat UIDs).

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 tells when to use and when to use alternatives, and states the precondition that at least one of flagsToAdd/flagsToRemove must be non-empty.

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?

Annotations already indicate readOnly and idempotent, but description adds significant behavioral context: partial result detection (scanned/truncated), exactness of total/unread counts, cap on aggregations, and rejection of non-selectable containers with actionable errors.

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 purpose, then parameter behavior, then edge case. Two key sentences plus a third for error handling. No wasted words; every sentence earns its place.

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 low complexity (2 simple params, no output schema), description is thorough: covers purpose, parameter details, behavioral traits (truncation detection, exact counts), and error handling. No gaps for safe agent invocation.

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 covers both parameters (100% coverage), but description adds valuable nuance: for scanLimit, clarifies that total/unread counts are always exact while aggregations are capped, and that response includes scanned/truncated; for folder, restates default. Adds meaning 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?

Description clearly states 'Return aggregate stats for a folder' with specific details about total/unread counts and scanned-envelope aggregations (oldest/newest/total bytes), distinguishing it from sibling tools like count_messages or list_folders.

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 clear context on scanLimit defaults and max, explains how to detect partial results via scanned/truncated response fields, and mentions error handling for non-selectable containers, but does not explicitly state when to use this tool versus 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?

The description discloses response format (sent-copy token), sanitization scope, and potential security risks of plain-text content passing through. This goes well beyond the annotations (readOnlyHint: false, etc.), which already indicate a write 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 relatively long but well-structured with a clear flow: core function, response format, then security details. It front-loads the action but includes some detailed security guidance that could be trimmed without losing essential info.

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 (12 parameters, no output schema), the description covers behavioral aspects like response token, sanitization, dryRun preview, attachment handling, and mutual exclusions. It feels complete and addresses key user concerns.

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 100%, so baseline is 3. The description adds context like mutual exclusivity and response tokens but does not significantly alter understanding of individual parameters beyond their schema descriptions.

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 verb 'Forward' and the resource 'an email message', and adds detail about threading headers. It distinguishes from siblings like send_email by specifying it reads the original message and forwards it.

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 the tool is for forwarding emails but does not explicitly state when to use it versus alternatives (e.g., reply_email, send_email). It provides security usage guidance but lacks direct comparison with siblings.

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?

Annotations already indicate read-only and idempotent. The description adds details: chronological sorting, folder spanning, UID collision avoidance, and rewriting of folder/UID for user folders. No contradictions.

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 sections (preferred, legacy, scope) and front-loaded main purpose. However, some explanatory text could be trimmed; still clear and organized.

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 of IMAP threading, the description covers algorithm, limitations (forwards), and pitfalls (UID collisions). Even without output schema, it provides enough return value 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?

Schema coverage is 100% (all parameters described). The description adds value by explaining the rationale behind messageId vs uid+folder and the default folder walk, but baseline is 3 due to full schema coverage, so 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?

The description clearly states it retrieves all messages in a conversation thread by walking In-Reply-To and References headers, specifying the verb, resource, and mechanism. It distinguishes from siblings like 'list_messages' by focusing on threading.

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 explicitly recommends using messageId over uid+folder due to UID collisions, explains the legacy alternative, and clarifies the scope (only reply chain, not forwards). Provides 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?

Annotations already mark the tool as read-only and idempotent. The description adds behavioral insight by stating it does not download the body and lists the returned metadata fields, enhancing transparency.

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 two concise sentences, front-loaded with the main purpose and followed by a brief explanation of output and usage. No extraneous content.

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 lack of output schema, the description adequately lists return fields (part numbers, filenames, content types, sizes) and references download_attachment. It is complete for the tool's simple purpose.

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 100%, with both parameters well-documented. The description adds no further parameter-level detail, only referencing them implicitly.

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 attachment metadata without downloading the body, specifying the resource (attachments for a message) and action (list). It distinguishes from download_attachment by noting it does not fetch content.

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 explicitly mentions using the output with download_attachment, providing a clear usage flow. It implicitly says to use this tool before download, but does not explicitly exclude other uses.

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?

Annotations already provide readOnlyHint and idempotentHint. The description adds critical behavioral context: counts are stale/cached from IMAP STATUS. This warns agents about potential inaccuracy, which goes beyond the annotations.

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

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

Two sentences: first states purpose clearly, second provides a crucial caveat and alternatives. No wasted words, front-loaded with key 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?

For a zero-parameter, read-only tool, the description fully covers what the tool does, the nature of its output (folder names with counts), and an important limitation (stale counts). No output schema is needed for this simple case.

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 no parameters, so schema coverage is 100% and no parameter info is needed. The description doesn't add param details, which 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?

The description clearly states the tool lists email folders/mailboxes with message counts. It uses the specific verb 'list' and identifies the resource, and the warning about staleness differentiates it from siblings like count_messages and folder_stats.

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 explicitly states when to use this tool (listing folders with counts) and when not to rely on it (for authoritative decisions). It names alternatives (count_messages, folder_stats) for exact counts, providing clear 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?

Annotations indicate readOnlyHint and idempotentHint. The description adds detailed behavioral context: date sort default, pagination mechanics, potential skips/duplicates in certain folders, and the error behavior for namespace containers. No contradictions.

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: first sentence states core purpose and output, then error behavior, then a detailed pagination note. No fluff; every sentence adds value. Uses bold for key terms.

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 5 parameters (all well-described in schema), no output schema, and 29 siblings, the description covers main functionality, pagination nuances, and edge cases (namespace error). It provides sufficient context for an agent to use the tool correctly.

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 100%, so baseline 3. The description adds meaning beyond schema: explains that sortByUid makes beforeUid pagination exact, includeSnippet adds a body preview, and default sorting is by date newest first. This extra context warrants a 4.

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 recent messages from a folder, sorted by date, and specifies returned fields (subject, sender, date, flags). It also distinguishes from siblings like search_messages by mentioning when to use that tool for date windows.

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 explicit guidance on pagination: when to use beforeUid, when to set sortByUid for exact paging, and when to use search_messages for precise date windows. It also warns about namespace containers causing errors.

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 complements annotations (idempotentHint=true, destructiveHint=false) by detailing the dryRun preview behavior and the exclusive date constraint. It adds useful behavioral context beyond what annotations provide, though it could mention error handling or performance.

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?

Two concise sentences front-load the main purpose and key options. Every word is necessary; no fluff or 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 simple tool with 3 optional parameters and no output schema, the description covers the essential behavior (marking read, date filtering, dry run). It lacks mention of return value or error cases, but given the tool's low complexity, it is adequate.

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 100%, so baseline is 3. The description adds minor value by repeating the dryRun preview and noting the exclusive date format for olderThan, but these are already implied in the schema descriptions. No additional semantics 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?

The description clearly states the action ('Mark all unread messages in a folder as read') and the scope (all unread messages in a folder, optionally filtered by date). This distinguishes it from sibling tools like bulk_update_flags or update_message_flags by being specifically for the 'mark as read' action on all unread messages in a folder.

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 basic usage context (dryRun, date filtering) but does not explicitly state when to use this tool versus alternatives (e.g., for single messages use update_message_flags). It does not include when-not-to-use guidance or comparison with siblings.

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?

Disclosures that the message gets a new UID and that original UID becomes invalid, plus the per-folder UID caveat. Adds significant behavioral context beyond annotations (destructiveHint) by explaining what changes irreversibly.

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?

Two clear paragraphs: first states action and immediate effect, second explains UID caveat. Could be slightly more concise (e.g., second paragraph is explanatory but not wasteful). Good front-loading.

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?

Despite no output schema, the description explains result (new UID, old invalid) and provides essential caveats for safe usage. Covers what changes and how UIDs behave, making it complete for a move operation.

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 100%, and each parameter has a description in the schema. The description adds no additional parameter-level detail beyond what's in the schema, so baseline score of 3 applies.

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?

Explicitly states 'Move an email message to a different folder', clearly specifying the verb (move) and resource (email message). Distinguishes from siblings like delete_message or copy operations by focusing on move behavior.

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 explicit when-to-use context (moving a single message) and warns about UID invalidity. Also directly recommends alternatives for thread-level operations: 'prefer get_thread / move_thread', giving clear direction.

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?

Beyond annotations (destructiveHint=true, idempotentHint=true), the description adds that moving is destructive, describes cross-folder walking behavior, and the dry run preview mechanism. It does not cover error cases or permissions, but provides sufficient behavioral context.

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

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

The description is three concise sentences, each adding distinct information: purpose, default vs. acrossFolders behavior, and dry run capability. No redundant or irrelevant content; front-loaded with the core action.

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 (4 parameters, no output schema, destructive action), the description covers essential aspects: operation, parameter effects, and preview mode. It lacks return value details but is sufficient for selecting and using the tool correctly.

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 covers all parameters with descriptions (100% coverage). The description adds value by integrating the parameters into the workflow, e.g., explaining the default scoping and the effect of acrossFolders, which complements the schema details.

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 every message in a thread to a destination folder,' specifying the verb (move) and resource (thread messages). It distinguishes from siblings like move_message (single message) and bulk_move (arbitrary set), and explains the default scoping behavior.

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 acrossFolders and dryRun parameters to modify behavior, and implies that for single-message moves, move_message should be used instead. However, it does not explicitly list when not to use this tool or name alternative tools.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses critical behavioral details: body truncation (default 50k chars), preferHtml behavior with security warnings, stripUrls purpose, and showHeaders option. It also warns about prompt-injection risks, adding high transparency.

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 core functionality is front-loaded, but the two lengthy security caveats (prompt injection, preferHtml) significantly increase length. While important, they could be more concise, and the overall description is longer than necessary for a simple read operation.

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 6 parameters and no output schema, the description covers return format (headers + body), truncation, HTML options, header selection, and URL stripping. It lacks details on which specific headers are always included, but overall provides sufficient context for correct usage.

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 100%, so baseline is 3. The description adds value by explaining default behaviors (preferHtml false yields stripped HTML, stripUrls drops link URLs) and security implications of preferHtml, justifying an above-baseline score.

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 reads a specific email by UID, returning headers and body. It distinguishes from sibling tools like list_messages which only list summaries, by requiring a UID for targeted retrieval.

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 (e.g., list_messages for previews, search_messages for filtering). Usage is implied for reading a known message's full content, but no exclusions or alternative pointers 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?

Annotations already indicate destructive behavior (destructiveHint=true). Description adds the error condition for missing source path but does not disclose additional side effects like whether renaming affects subfolders or permissions.

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?

Two concise sentences with no unnecessary words. Front-loaded with the primary action and critical error condition.

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 absence of output schema and many sibling tools, the description is reasonably complete for a simple rename operation. Could mention if renaming cascades to contained messages but not essential.

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?

Input schema covers both parameters with descriptions, achieving 100% coverage. Description reiterates path prefixes but adds minimal new meaning 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 the action (rename a mailbox folder or label), specifies error condition for nonexistent source path, and clarifies it works for both 'Folders/' and 'Labels/' paths. Distinguishes from sibling tools like create_folder or delete_folder.

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 vs alternatives. The error condition is mentioned but not contrasted with other tools. Implies use for renaming only.

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?

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds behavioral details: it sends with proper threading headers, the response leads with [sent-copy:verified|unverified], and reply-to tokens don't apply. No contradiction with annotations.

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

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

The description is brief (two sentences), front-loaded with the core action, and every sentence adds value. 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 no output schema and high schema coverage, the description covers key behavioral aspects (reply-all, threading, response format, equivalence to reply_email, and lack of reply-to tokens). It is complete for an agent to understand usage.

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 100%, so the description does not need to elaborate on parameter semantics. It mentions equivalence to reply_email with replyAll: true, which provides context but does not add new meaning to individual parameters beyond their schema descriptions.

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 replies to all recipients (sender + original TO + original CC) excluding the authenticated user, and sends with proper threading headers. It distinguishes itself from reply_email by being a dedicated tool for reply-all, and mentions its equivalence to reply_email with replyAll: true.

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 context by noting equivalence to reply_email with replyAll: true, implying use when replying to all. It also explains that [reply-to:*] tokens do not apply, but does not explicitly state when not to use or contrast with alternatives like forward_email.

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?

Describes the response token format, threading headers, and the effect of the dryRun parameter. Annotations are non-contradictory, and the description adds significant behavioral context beyond annotations, such as token behavior and dryRun preview.

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?

Three short, front-loaded sentences with no redundancy. Every sentence adds essential information: purpose, token behavior, and usage alternatives.

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 11 parameters and no output schema, the description covers main behavior, token, and alternatives. It could mention default behaviors like quoting or auto-marking read, but the core information is sufficient for an email reply 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?

Input schema covers all parameters (100% coverage), so baseline is 3. The description adds value by explaining the dryRun parameter's preview effect and advising against replyAll in favor of the dedicated tool, which is helpful but not extensive.

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 'Reply to an email message' with details about threading headers, clearly differentiating from siblings like send_email and reply_all_email. The verb and resource are specific and unambiguous.

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

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

Provides explicit guidance on when to use alternative tools (send_email for Reply-To control, reply_all_email for reply-to-all), and clarifies that the [reply-to:*] tokens do not apply. This is exemplary 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?

Annotations (readOnlyHint, destructiveHint, idempotentHint) are all false. The description adds significant context: atomic replace with replaceDraftUid (APPEND-then-delete), folder fallback behavior, and that the folder is immutable. No contradiction with annotations.

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

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

Two well-structured paragraphs with front-loaded purpose. Every sentence provides necessary detail. No redundancy or fluff. The historical note is 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?

Given 12 parameters and no output schema, the description covers key behavior: draft location, immutable folder, atomic replacement, and parameter interactions (mutual exclusivity of body/markdownBody, sanitization defaults). It is complete for agent decision-making.

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 100%, so baseline is 3. The description adds value beyond schema by explaining the atomic replace workflow for replaceDraftUid and the rationale for missing folder parameter. This enhances understanding.

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 an email as a draft without sending it', which is a specific verb+resource combination. It distinguishes from sibling tools like send_email by emphasizing the draft nature and lack of delivery.

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 (save draft) and provides context on the fixed Drafts folder destination, preventing misuse. It lacks explicit comparison to alternatives but implies usage via behavioral details.

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 valuable behavioral insights beyond the readOnlyHint and idempotentHint annotations: indexing delays for new messages, immediacy of 'from' searches, and error handling for non-selectable folders. This helps the agent understand non-obvious behaviors.

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 (four sentences) and front-loaded with the primary purpose. Each sentence serves a distinct role: purpose, output format, performance caveat, error behavior. 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?

For a tool with 17 parameters and no output schema, the description covers key behaviors (indexing, errors, sorting) but does not explain filter combination logic (AND) or return structure details beyond 'summaries'. It is mostly complete but could explicitly state that multiple criteria are combined.

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 100%, so baseline is 3. The description does not significantly elaborate on parameters beyond the schema's own descriptions (e.g., 'Filter by sender email address or name'). The note about indexing delays relates to parameters but adds no new parameter-specific meaning.

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: 'Search for messages in a folder by various criteria'. It names the verb (Search), resource (messages), and provides context like sorting by date. This distinguishes it from sibling tools like list_messages (which lists all) and count_messages (which counts).

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 lacks explicit guidance on when to use this tool versus alternatives (e.g., list_messages, count_messages). It does not contrast with siblings or state when filtering is appropriate. Users must infer usage from the listed criteria.

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 goes beyond annotations by detailing sanitization behavior (default true, stripping scripts), plain-text handling, and Proton SMTP specifics like replyTo rewriting and fromName spoofing protection. Annotations provide only basic hints, so the description adds substantial value for agent decision-making.

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

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

The description is extremely concise (two sentences) and front-loaded with the core action. Every sentence provides essential information without repetition or fluff.

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?

Despite 13 parameters and no output schema, the description covers key behavioral aspects (sanitization, plain-text, fromName restrictions, dryRun, replyTo behavior). It omits no critical details given the richness of the schema descriptions.

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 100% schema description coverage, the baseline is 3. The description adds overarching context about sanitization policy and behavioral defaults that are not fully captured in individual parameter descriptions. This enhances understanding 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 'Send an email using Proton Mail SMTP', which is a specific verb-resource pair. It distinguishes from sibling tools like forward_email or reply_email by focusing on composing a new message. The additional detail about HTML sanitization further clarifies the tool's 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 does not explicitly state when to use this tool versus alternatives like reply_email or forward_email. While the purpose implies it's for new emails, there is no direct guidance or exclusion. The usage context is mostly implicit.

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?

Annotations already declare readOnlyHint and idempotentHint. The description adds substantial behavioral context: lowercased email keys, direction field ('self'/'received'), scanning limits (default 5000, max 20000), and the excludeSelf default change (v1.0.0). It also explains response indicators (scanned/truncated). No contradiction with annotations.

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

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

The description is detailed but reasonably concise, with key information upfront. However, the versioning note about v1.0.0 could be integrated more smoothly. Still, every sentence adds value, and the structure is logical.

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 output schema, the description explains response structure (direction, scanned/truncated). It covers all parameters and behavioral nuances. With 6 parameters and no required ones, it's fairly complete. Minor gaps: could mention default folder (INBOX) is already in 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?

Schema coverage is 100% (all 6 parameters have descriptions). The description adds extra meaning: folder note about All Mail including Sent, since/before date formats (inclusive/exclusive), limit/scanLimit ranges, and excludeSelf default change. This goes beyond the schema, justifying a score above baseline 3.

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: 'Return a frequency table of top senders for a folder, optionally filtered by date range.' It uses a specific verb ('Return') and resource ('frequency table of top senders'), distinguishing it from siblings like folder_stats, count_messages, or search_messages, which have different outputs.

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 tells when to use (when needing top senders frequency) and mentions key behavior changes (excludeSelf default). However, it does not explicitly state when not to use or compare to alternative tools. The context is clear, but exclusion guidance is missing.

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 goes beyond annotations by disclosing that user-defined keywords may be silently dropped by Proton Mail Bridge and that UIDs are per-folder. It also mentions the response reports 'no-op (not applied)' for unapplied flags. However, it does not explicitly confirm idempotency (already in annotations).

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: main purpose first, then flag types, then critical caveats. It is not overly long, but some sentences could be condensed. Still, every sentence adds necessary value, making it 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 complexity of modifying flags and the absence of an output schema, the description provides sufficient context: it covers flag semantics, the Proton Bridge bug, and UID scoping. It lacks explicit differentiation from sibling tools, but overall it is complete 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?

Input schema descriptions cover all 4 parameters (100% coverage), but the description adds valuable context: flag format (backslash prefix for system flags, no backslash for user keywords), and the UID+folder pair caveat. This extra meaning justifies a score above the baseline of 3.

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 action: 'Add or remove flags on an email message.' It specifies the verb (add/remove), resource (email message), and provides details on system flags and user-defined keywords, leaving no ambiguity about the tool's 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 implicitly indicates usage for single-message flag management, but it does not explicitly differentiate from sibling tools like 'bulk_update_flags' or 'flag_thread.' No guidance is given on when to use this tool vs. alternatives, which is a notable gap.

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?

Annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) are complemented by detailed behavioral context: labels are additive, message stays in folder, strict vs idempotent behavior, error conditions for missing label on add, and silent no-op for remove. No contradiction.

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 moderately sized with three paragraphs, front-loaded with core action, then behavior, then caveat. Every sentence adds value. Minor room for conciseness but overall efficient.

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?

No output schema, but for a mutation tool, return value is less critical. Description covers behavior, error conditions, and important caveat. Considering the complexity and siblings, it is sufficiently complete for correct agent usage.

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 100%, so baseline is 3. Description adds meaning: explains label path format (full paths under Labels/), provides examples, and clarifies that UID must be paired with folder to avoid ambiguity.

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: 'Add or remove Proton labels on a message.' It distinguishes from siblings like bulk_update_labels (handles multiple messages) and move_message (moves folder). The additive nature and namespace are explicitly mentioned.

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 explicit when-to-use and when-not-to-use: adds are strict (must exist, else error), removes are idempotent (silent no-op). It advises creating labels first with 'create_label' and warns about the UID+folder pair caveat.

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