Proton Mail Bridge MCP

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

Annotations provide destructiveHint: true, and the description adds context that actions are 'reversible' and supports dryRun for previewing impact. It also mentions scoping via unreadOnly and index refresh via syncBefore. This goes beyond the annotation without contradicting it.

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: purpose, usage, and alternative. Front-loaded with the essential description, no filler, 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?

For a 7-parameter tool with no output schema, the description covers the core action, use case, key scoping options, and alternative. It doesn't detail return values or failure mode, but the schema covers parameters and destructiveHint covers risk. Very solid overall.

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 high (86%) and all parameters have descriptions. The description reiterates dryRun, unreadOnly, and syncBefore but doesn't add new parameter-level meaning beyond what the schema already supplies. Minimally viable, not lacking but not additive.

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 uses a specific verb ('Apply') and identifies the resource ('every message in a normalized thread'), immediately distinguishing it from single-message tools. It also names example actions ('archive or mark-read') and differentiates from batch_email_action by threadId vs emailIds.

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 states when to use the tool ('Use when you want to act on a full thread identified by threadId') and when to prefer an alternative ('Prefer batch_email_action when you have explicit emailIds rather than a threadId'). This gives clear decision 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 provide destructiveHint=false, so the agent knows it's not destructive. The description adds no major behavioral context beyond the move semantics (e.g., it doesn't mention whether archival removes from the current folder, whether it's reversible, or permission needs). Since the annotation already covers the safety profile, a score of 3 is appropriate—adequate but with room for more behavioral detail.

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: the first sentence states the core action, the second gives usage context, and the remaining three sentences list alternatives. Every sentence adds value, with no redundancy or fluff. It is front-loaded and easy to scan.

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 one parameter and no output schema, the description fully covers what the tool does, when to use it, and which alternatives to prefer. The annotation covers destructiveness, and the schema covers the parameter. No additional context is 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?

Schema description coverage is 100%, with the emailId parameter clearly documented as 'Composite email id in FOLDER::UID format, as returned by get_emails or search_emails.' The description does not add extra parameter semantics, so the 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?

The description clearly states the action: 'Move a single email to the standard Archive folder.' It specifies the verb (move), resource (email), destination (Archive folder), and scope (single). It also distinguishes itself from sibling tools by naming trash_email, move_email, and batch_email_action as alternatives, making it unmistakable.

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 when-to-use guidance: 'Use for messages that are resolved but worth keeping long-term.' It also gives clear exclusions and alternatives: 'Prefer trash_email when the message is no longer needed. Prefer move_email to route to a custom folder. Prefer batch_email_action for archiving multiple emails at once.' This fully addresses selection vs. 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 adds behavioral context beyond the destructiveHint annotation: details like 'delete (permanent expunge)', dryRun support, and continueOnError behavior, and does not contradict 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?

Concise at 4 sentences, front-loaded with purpose and usage, then actions, then alternatives. 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?

For a batch action tool without output schema, the description fully covers input semantics, supported actions, usage context, and sibling alternatives. No gaps.

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 80% with descriptions on most parameters. The description adds semantics for the action enum (lists and explains each action) and clarifies emailIds format. Slightly redundant but helpful.

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 'Apply one action to a known list of email IDs' with specific verb and resource, and distinguishes from sibling tools like bulk_delete, apply_thread_action, and empty_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?

Explicit usage guidance: 'Use when you already have the IDs' and 'Prefer bulk_delete when selecting by search criteria', etc., providing clear when-to-use and 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?

Beyond the destructiveHint annotation, the description discloses critical behaviors: the XOR relationship between emailIds and match, the irreversible nature of permanent:true versus moving to Trash, the availability of dryRun for preview, and the safety mechanism of maxBatchSize to prevent runaway operations. 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 compact and well-structured, leading with the core purpose, then explaining key parameters, and finally providing decision guidance. Every sentence adds value and there is no redundant or filler 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?

For a complex tool with 7 parameters, a nested match object, and no output schema, the description covers all essential usage patterns, safety considerations, and sibling alternatives. It gives the agent enough context to invoke the tool correctly and safely.

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?

While the schema covers 86% of parameters, the description adds crucial semantic meaning: the XOR constraint, that folder is required with match, the purpose of dryRun as a preview, and the safety role of maxBatchSize. These details significantly enhance understanding beyond the schema's own 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 ('Delete'), the resource ('emails'), and the two modes of operation (explicit ID list or search criteria). It distinguishes itself from siblings by explicitly recommending empty_folder, delete_email, and batch_email_action for alternative scenarios.

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 context: 'Use when you have specific IDs to delete or want to filter by sender, subject, or date range.' It further provides clear alternatives with 'Prefer' statements, making it obvious when to choose this tool over related ones.

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 include operations in one IMAP pass, dryRun support, and max batch limit. The annotation destructiveHint: false is consistent. No contradictions noted, but could mention that moves are reversible or if permissions required.

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 concise sentences with no redundancy. Key information is front-loaded: purpose, usage, and differentiation.

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 essential aspects: method of selection (IDs or criteria), dryRun, batch size limit. Missing details on return value or error handling, but acceptable without 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 100% schema coverage, the description adds value by explaining the XOR relationship between emailIds and match, and that folder is required when using match. This context 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 the action (move multiple emails), resource (emails in one IMAP pass), and explicitly differentiates from the sibling tool move_email for single-message moves.

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: when to use (bulk moves), when not to use (single-message use move_email), and how to use (XOR between emailIds and match criteria, dryRun preview, max batch size).

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 only provide destructiveHint: false. The description adds valuable behavioral context: it discloses that the operation modifies flags, and importantly reveals the return behavior 'Returns notApplied[] per message for flags the server silently dropped.' This goes beyond the sparse annotation, though it does not mention potential side effects like runaway operations (covered in schema) or permission 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 four sentences, each purposeful: purpose, usage, input constraints, and alternative. It is front-loaded with the main action and provides critical details 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 the tool's complexity (7 params, nested match object, no output schema), the description covers essential context: batch operation, XOR input modes, return behavior, and when to prefer the single-message alternative. It does not address edge cases like empty flag arrays or conflicting flagsToAdd/Remove, but it provides a solid operational picture.

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 high (86%), so baseline is 3. The description adds key parameter semantics beyond the schema, notably the XOR relationship: 'Accepts emailIds[] OR match+folder (XOR).' It also clarifies flag format with an example. This adds meaning that is not obvious from individual 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's function: 'Add or remove IMAP flags on multiple messages simultaneously.' It specifies the resource (IMAP flags) and the scope (multiple messages), and distinguishes itself from sibling tools like update_message_flags by emphasizing batch operations and the XOR input mode.

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 explicit usage context: 'Use when the same flag change... should apply to several messages' and provides an explicit alternative: 'Prefer update_message_flags for a single message when you need per-flag server verification.' This clearly guides 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?

The annotations set destructiveHint to false, which aligns with the non-destructive nature of adding/removing labels. The description mentions the operation but does not detail behavioral aspects like idempotency, rate limits, or what happens with duplicate operations. With annotations covering the safety profile, a 3 is appropriate.

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 sentences with no filler. Each sentence conveys essential information: purpose, when to use, and parameter constraint. It is front-loaded with the main 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 tool has 7 parameters, a nested object (match), and no output schema, the description adequately explains the two modes of operation and the maxBatchSize safeguard. It is complete enough for correct invocation, though more detail on return values or error cases could be added.

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 86%, so most parameters are already described. The description adds value by explaining the XOR relationship between emailIds and match+folder, noting default maxBatchSize (500), and giving an example for labelsToAdd. This improves 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 the tool's function: 'Add or remove Proton labels on multiple messages simultaneously.' It specifies the resource (labels) and action (add/remove), and distinguishes it from sibling tools like 'bulk_move'.

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 when the same label change should apply to several messages.' It also explains the XOR constraint between emailIds and match+folder, helping the agent choose parameters. However, it does not explicitly advise against using for single messages.

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 minimal annotations (only destructiveHint: false), the description discloses key behaviors: returns canceled: false if already sent, and throws when PROTONMAIL_SEND_DELAY_SECONDS is 0. It doesn't mention the success return value, but it covers edge cases well.

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 with no filler. The main action is front-loaded, and limitations are stated efficiently 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 the operation, edge cases, and error behavior. It lacks an explicit success return value, but the overall context is sufficiently complete for an 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?

The schema already fully describes the only parameter (id) with 100% coverage, and the description adds no additional parameter semantics. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states 'Cancel a send_email call that was queued', using a specific verb and resource. It also differentiates from sibling tools like cancel_snooze by referencing the PROTONMAIL_SEND_DELAY_SECONDS mechanism.

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 the tool (while the item is pending) and when not to use it (if delay is 0, it throws). It also clarifies the outcome if the item has already sent, giving clear usage 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?

The description goes beyond the destructiveHint=false annotation by explaining the side effect (moving back to original folder) and the error behavior (throws if no longer snoozed). This is transparent about state changes and failure modes.

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 sentences, front-loaded with the primary action, and includes necessary edge-case behavior in the second sentence. Every word 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 simple tool with one well-documented parameter and no output schema, the description fully covers what happens, when it throws, and the side effect. It is complete 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?

The input schema already provides 100% coverage for the single 'id' parameter, including a clear description ('The id returned by snooze_email'). The description does not add extra semantic detail, but none is needed because the schema is sufficient.

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 uses a specific verb ('Wake') and resource ('snoozed email'), and clarifies the action ('moving it back to its original folder before wakeAt'). It clearly distinguishes from the sibling tool 'snooze_email' by being its inverse.

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 clearly implies when to use (when an email is currently snoozed and you want to wake it early) and provides an important boundary condition ('No effect (throws) if already woken or canceled'). However, it does not explicitly reference alternatives or mention that re-snoozing can be done with snooze_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 behavioral effect (evicts caches) and context (stale data). Annotations declare destructiveHint=false, and description aligns, adding detail about what is destroyed (in-memory caches but not index). 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?

Two sentences: first states action and scope, second gives usage guidance and sibling differentiation. Concise and front-loaded 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?

Given zero parameters, no output schema, and clear annotations, the description is fully complete. It covers purpose, usage, and what it does not do, which is sufficient for agent decision.

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 in schema (0 params), so baseline is 4. Description does not need to add param info; it correctly implies no input required.

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 (evict all in-memory caches) and specifies the cache types (folder list, message metadata, analytics data). Distinguishes from sibling tool 'clear_index' by noting it does not affect the persistent SQLite index.

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: when cached data appears stale after external mailbox changes (e.g., via Proton webmail). Provides explicit exclusion: 'Does NOT affect the persistent SQLite index — use clear_index for that.'

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 destructiveHint annotation, the description discloses that the operation is irreversible, deletes all indexed metadata and search history, and specifically excludes in-memory caches. It also instructs the necessary follow-up action (sync_emails), providing full transparency about consequences.

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 four tightly written sentences, each earning its place: what, when, how to recover, and what it does not do. It is front-loaded with the core action and avoids any 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?

Given that this is a destructive irreversible action with no output schema, the description fully addresses the agent's needs: what exactly is deleted, under what circumstances to invoke, the irreversibility, and the required rebuild step. The sibling clear_cache is explicitly differentiated, leaving no ambiguity.

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 takes zero parameters, so there is no parameter schema to elaborate on. The description nevertheless clarifies what the tool operates on (persistent SQLite index) and the irreversibility, which is sufficient for an agent to invoke without additional parameter context. Baseline 4 per rubric for zero-param tools.

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 opens with a specific verb and resource: 'Delete the entire persistent SQLite mailbox index from disk.' It clearly distinguishes the tool from sibling clear_cache by stating the scope is the persistent index, not in-memory caches.

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 it ('reset a corrupted or schema-incompatible index') and provides alternatives: after clearing, call sync_emails to rebuild, and for in-memory caches use clear_cache. This is explicit when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, indicating no side effects. The description adds transparency by stating it counts without fetching message data, confirming lightweight 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?

Two sentences, extremely concise, front-loaded with key action and purpose. No unnecessary words or repetition.

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 the description implies a count result. For a simple count tool, it adequately covers what the tool does and when to use it. Could explicitly state return value (number) 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 coverage is 100% with all 15 parameters documented. The description does not add specific parameter meaning beyond schema descriptions, only stating 'live IMAP search criteria' broadly. 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 tool counts messages matching live IMAP search criteria, explicitly noting it does not fetch message data. It explains the purpose (preview count before running a search) and distinguishes from folders_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 says when to use (to preview how many results a search would return before running it) and when not to use (prefer folder_stats for simple unread/total count on one folder without filters), providing a clear alternative.

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 only include destructiveHint=false, so description carries the burden. It discloses local SQLite persistence, optional sync to the Proton Drafts IMAP folder, and the return of a draftId for later operations, adding meaningful context beyond the annotation.

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 action and storage, then usage, alternatives, and return value. Every sentence earns its place with no waste.

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 having no output schema, the description explains the draftId return and the draft lifecycle (update, sync, send). With a rich input schema and clear alternatives, the description is complete enough for correct tool selection and 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 description coverage is 91%, so the schema handles most parameter meaning. The description adds context for sync behavior and return value but does not detail individual params; 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 uses a specific verb and resource: 'Save a new outbound message as a local draft in SQLite', clearly distinguishing it from sibling tools. It also explicitly contrasts with create_reply_draft and create_forward_draft.

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 usage guidance: 'Use to compose and review before sending' and directs to specific alternatives for replying ('create_reply_draft') and forwarding ('create_forward_draft').

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 destructiveHint: false only. The description adds behavioral details: it creates a folder via IMAP, disallows system folders, and returns the created path on success. This adds context beyond the minimal annotation.

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 concise sentences, each adding essential information: action, path conventions, prohibited folders, and return 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?

For a simple 1-parameter tool with no output schema and minimal annotations, the description covers the key aspects: what it does, how to use it, constraints, and expected outcome. No gaps.

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 by providing concrete path examples ('Folders/Receipts', 'Labels/') and warning against system folders, which enhances understanding beyond the schema's generic description.

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: 'Create a new mailbox folder via IMAP.' It specifies the resource (mailbox folder) and distinguishes between user folders and labels using the 'Folders/' and 'Labels/' prefixes, which differentiates it from sibling tool 'create_label'.

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 when not to use the tool (system folders) and how to construct paths (using 'Folders/' and 'Labels/' prefixes). It implies usage context (for user-created folders and labels) but does not explicitly name alternative tools like 'create_label'.

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 only provide destructiveHint=false, so the description carries most of the behavioral burden. It discloses key behaviors: the original message is quoted, attachments are preserved unless configured otherwise, no immediate send occurs, and a draftId is returned for later update or send. This goes well beyond the annotation while remaining accurate.

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 tight sentences with no filler. The primary action and key behavior are front-loaded, and the alternative and return value are each covered in one sentence, giving maximum signal per word.

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 10-parameter tool with no output schema and sparse annotations, the description covers the essential operational context: what the tool does, when to use it, the key alternative, and what it returns (draftId). It could mention the required recipient parameter or sync behavior, but those are already visible in the schema, so the description is sufficiently complete for correct tool selection and 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 description coverage is 100%, so the schema already documents all parameters, establishing a baseline of 3. The description adds some context—'quoted body' clarifies how body relates to the original message, and 'preserving its attachments' gives meaning to includeAttachments—but it does not substantially enrich the parameter docs overall.

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 a specific verb ('Create a forward draft'), a clear resource ('an existing email'), and core behaviors (pre-filling the original as quoted body, preserving attachments). It distinguishes this tool from forward_email by highlighting the staging-for-review purpose, so an agent can tell them apart without opening schemas.

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 says when to use it: when you have an emailId and want to stage a forward before sending. It also names the alternative — 'Prefer forward_email to send immediately without saving' — giving a clear when-not-to-use condition.

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 destructiveHint=false annotation, the description adds idempotency context, though it does not cover potential error cases.

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 clear, front-loaded information and zero 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 tool with one parameter and no output schema, the description adequately covers purpose, safety, and alternative, leaving no critical gaps.

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 coverage, the schema already describes the parameter, and the tool description repeats the prefix behavior without adding new info. 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 tool creates a Proton label under the Labels/ namespace, distinguishing it from create_folder which creates folders under Folders/. The verb and resource are 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?

Explicitly states when to use this tool vs the sibling create_folder, and notes idempotency implying safe re-call.

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 only declare destructiveHint=false. The description adds valuable behavioral context: pre-fills To/Subject/quoted body, stages reply for review (not sent), and returns a draftId. It stops short of explaining draft persistence or sync implications, but for a non-destructive draft tool this 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?

Four sentences, no fluff. Purpose is front-loaded, followed by usage and return value. Every sentence contributes actionable information 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?

Despite 9 parameters, the schema fully documents them. The description covers what the tool does, when to use it, key alternatives, and return value (draftId). This is complete enough for an agent to select and invoke correctly without additional 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 covers all 9 parameters with individual descriptions (100% coverage), so description doesn't need to re-articulate each parameter. It does add context around emailId's role ('original message') and that the body is prepended, but this is not a major addition 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?

Clearly states the action: 'Create a reply draft for a specific email, pre-filling To, Subject, and quoted body from the original message.' Distinguishes from siblings by explicitly naming create_thread_reply_draft (threadId) and reply_to_email (send immediately), so the tool's unique role is evident.

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 usage conditions: 'Use when you have an emailId and want to stage the reply for review before sending' and gives direct alternative guidance: 'Prefer create_thread_reply_draft when you only have a threadId. Prefer reply_to_email to send immediately.' This is textbook when-to-use vs 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?

Annotations only provide destructiveHint: false, which is minimal. The description compensates by disclosing key behaviors: placeholder auto-detection and storage, and failure on duplicate names. This adds meaningful context beyond the sparse annotation, though it does not mention return values or authentication.

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, front-loaded with the core purpose. The first sentence states what the tool does; the second adds important behavior and failure mode. There is no filler, tautology, or 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?

For a simple creation tool with full schema coverage, the description covers the essential elements: purpose, placeholder behavior, and duplicate handling. It does not explain return values, but no output schema exists and the tool's simplicity mitigates the need. It is sufficiently complete 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?

The input schema already provides 100% description coverage for all four parameters, so the baseline is 3. The description adds a small behavioral note about placeholders in subject/body but does not materially enhance parameter semantics beyond the schema. It correctly leaves detailed parameter meaning to 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 opens with 'Save a reusable email template', a specific verb+resource that clearly defines the tool's function. It distinguishes from sibling tools like list_templates, get_template, delete_template, and render_template by focusing on the creation action. Additional details about placeholders and uniqueness add clarity without ambiguity.

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 clearly implies when to use this tool (to save a new reusable template) and provides a practical guideline: it fails on duplicate names, so you must delete the existing template first to replace it. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of a 5.

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 context beyond the destructiveHint annotation by explaining the automatic selection of the latest inbound message and the return of a draftId. However, it does not disclose potential side effects such as syncing to remote (though syncToRemote parameter implies this). With annotations only covering destructiveHint, the description provides moderate additional transparency but not comprehensive behavior.

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 sentences, front-loaded with the core purpose, then usage guidance, alternative, and return value. Every sentence adds value with no fluff, making it highly concise and well-structured.

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

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

Given the tool has 11 parameters and no output schema, the description covers key context: purpose, use case, alternative, selection behavior, and return value. It does not elaborate on all parameters or potential caveats, but with full schema coverage this is sufficient. Slightly incomplete due to lack of mention of sync behavior or error cases, but generally complete for 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?

All parameters have descriptions in the schema (100% coverage), so the baseline is 3. The description aligns with the preferLatestInbound parameter by mentioning automatic selection of the latest inbound message, adding minimal extra meaning beyond schema. No significant parameter details are missing, but the description does not need to compensate.

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 reply draft from a threadId, with the specific behavior of automatically selecting the latest inbound message. It distinguishes itself from create_reply_draft by noting the preference when an emailId is available, and from other draft tools by its thread-based focus.

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 usage guidance is provided: 'Use when you have a threadId from get_threads or get_actionable_threads and want to stage a reply for review' and 'Prefer create_reply_draft when you already have a specific emailId.' This clearly states when to use the tool and when to use an alternative.

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 'destructiveHint' annotation, the description adds that the deletion is permanent and irreversible, and clarifies it only affects local SQLite storage, not the IMAP folder. This gives full 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 concise with three sentences, each serving a distinct purpose: stating the action, recommending usage, and clarifying limitations. No unnecessary 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?

The description covers all necessary aspects: what it does, when to use, what it doesn't do, and irreversibility. With a single parameter fully documented, no output schema needed, this is 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?

The only parameter, draftId, is fully described in the schema with examples of where it comes from. The description does not add further parameter details, but schema coverage is 100%, so a baseline score of 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 'Permanently delete a locally saved draft from SQLite,' specifying the action, resource, and context. It distinguishes itself from sibling tools like delete_thread and trash_email by focusing on local drafts and noting it does not affect the IMAP 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 explicitly advises when to use ('Use to discard a draft you no longer need') and when not to use ('Does NOT remove a matching draft from the Proton Drafts IMAP folder — that requires a separate mailbox action'), 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?

Beyond the destructiveHint annotation, the description adds critical behavioral context: 'Permanently delete', 'Irreversible', and 'via IMAP expunge' reveal the actual deletion mechanism. This clearly signals that the action cannot be undone, going beyond the annotation's generic destructiveness.

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 highly concise and front-loaded: the first sentence states the core purpose, followed by tightly worded usage guidelines and the final 'Irreversible' warning. Every sentence earns its place 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 the tool's moderate complexity (2 params, no output schema), the description covers purpose, usage timing, alternatives, and irreversibility. Combined with the complete schema, the agent has all necessary context to select and invoke 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 fully documents both parameters with detailed descriptions, including the composite format for emailId and the confirmation requirement for confirmed. The tool description adds no additional parameter-specific meaning, so the baseline 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?

The description clearly states the tool's purpose with a specific verb ('delete'), resource ('a single email'), and method ('via IMAP expunge'). It distinguishes itself from sibling tools by explicitly naming alternatives like trash_email, bulk_delete, and delete_thread.

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 when to use this tool: 'Use only when certain the message is no longer needed' and directly recommends alternatives: 'Prefer trash_email if recovery may be required', 'Prefer bulk_delete to delete multiple emails at once', and 'Prefer delete_thread to delete all messages in a conversation.'

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 destructiveHint annotation, the description adds important behavioral context: the operation is irreversible, limited to IMAP, and requires an empty folder. It also explicitly forbids system folders. This directly enhances transparency and aligns with the destructiveHint true flag.

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: three sentences, each adding necessary information. The main action is front-loaded, and there is no filler or repetition of schema details.

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 folder deletion tool, the description covers all essential context: prerequisites (empty folder), restrictions (system folders), and consequences (irreversible). Combined with the schema's parameter descriptions and the destructiveHint annotation, the tool is fully specified.

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 already provides 100% coverage with descriptions for both 'path' and 'confirmed'. The description does not add further detail about parameter semantics, so the baseline of 3 is appropriate given the high schema coverage.

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 and resource: 'Delete an empty mailbox folder via IMAP'. It distinguishes from siblings like create_folder, rename_folder, and empty_folder by specifying the empty-folder requirement and the IMAP context.

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 the tool ('The folder must contain no messages') and when not to use it ('Do NOT delete system folders'). It also provides actionable prerequisites ('move or trash all messages first'), which serves as clear usage 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?

Beyond the destructiveHint annotation, the description discloses that the operation is irreversible, that messages are not deleted, and that the label is an IMAP folder under Labels/. This adds critical behavioral context that annotations do not convey.

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 concise sentences, each providing essential information: what it does, the side effects on messages, and the alternative tool. No redundant wording, front-loaded with the primary 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 tool's simplicity (2 params, no output schema), the description covers the key aspects: the operation, irreversibility, message preservation, and alternative for folders. It is complete for an agent to safely use and select this 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 already covers both parameters with descriptions (name and confirmed), so the description does not need to add parameter details. The description mentions the Labels/ prefix handling, which is already in the schema. Baseline of 3 is appropriate at 100% schema coverage.

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 a Proton label, specifying the exact resource and scope (Labels/ namespace). It also distinguishes itself from the sibling delete_folder by explicitly contrasting the target resource.

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 explicit guidance on when to use this tool versus the alternative: 'For deleting a folder use delete_folder with a Folders/ prefix.' It also clarifies that the label itself is deleted, not the messages, which 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?

The annotations include destructiveHint: true, which already signals that the operation is destructive. The description adds that it deletes a 'saved' template, but this is a minor addition. It does not disclose side effects like permanence or whether the deletion can be undone, but with the destructive hint, the agent is aware of the risk.

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 one short sentence, front-loaded with the action, and contains no unnecessary words. It is concise and well-structured.

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 deletion operation with one parameter and a destructive hint, the description is sufficiently complete. No output schema is present, so no return value explanation is needed. The parameter is fully documented, and the tool's purpose is clear.

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 one parameter `id` with a description 'The template id,' providing 100% coverage. The description does not add any further detail about the parameter, so the baseline 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?

The description uses the specific verb 'Delete' and the resource 'saved email template,' which clearly distinguishes it from sibling tools like create_template, list_templates, and get_template. It's not a tautology because it specifies that the template is 'saved.'

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 no explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. However, the phrasing 'saved email template' implies that this tool is for deleting templates, not drafts or emails, so usage is implicitly 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?

Annotations include destructiveHint=true, and description expands by explaining the permanent parameter behavior (permanently expunges vs. moves to Trash). Also notes the tool is destructive by deleting all messages in the thread.

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 covers purpose and parameter behavior, second provides usage guidance. No extraneous content; 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?

Covers purpose and key parameter (permanent), but does not address dryRun, confirmed, or acrossFolders. For a destructive tool with 5 parameters, this leaves gaps. No output schema exists, but return values are not explained.

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?

Schemas description coverage is only 20% (only messageId described). Description adds meaning for the permanent parameter but does not explain dryRun, confirmed, or acrossFolders. While some value is added, it does not fully compensate for the low coverage.

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 tool deletes all messages in a thread using RFC 5322 Message-ID. Distinguishes from sibling tools like apply_thread_action by specifying when to use each.

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 this tool (when you have raw Message-ID) and when to prefer apply_thread_action (when you have local threadId from get_threads or get_actionable_threads).

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 destructiveHint annotation, description adds 'Irreversible', 'Permanently delete', condition 'Only available when PROTONMAIL_ALLOW_EMPTY_FOLDER=true', and explains two-step process with confirmed parameter.

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?

Four concise sentences, front-loaded with main action. Every sentence adds value: purpose, usage, availability, and parameter guidance. No waste.

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 2 parameters, destructive nature, and conditional availability, description fully covers purpose, guidelines, behavioral traits, and parameter usage. No need for 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?

Schema has 100% coverage, but description adds valuable context: folder path examples and explanation of confirmed parameter preview pattern, exceeding 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 'Permanently delete ALL messages in a folder at once' with specific verb and resource. Mentions alternatives like bulk_delete for subset removal, distinguishing from siblings.

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 says 'Use only when the goal is to clear an entire folder' and 'Prefer bulk_delete when removing a subset', providing clear when-to-use and when-not-to-use guidance with an alternative.

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 only include destructiveHint=false, so the agent knows it is not destructive. The description adds valuable non-obvious context: the tool writes raw RFC822 content to disk and requires an environment variable to be set. It does not contradict annotations, and the extra behavioral details (e.g., .eml format, backup use) go beyond what structured fields provide.

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 sentences, front-loaded with the core action and immediately providing use-case and configuration context. Every sentence adds value, and there is no redundant or filler 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?

For a simple 2-parameter export tool with no output schema, the description covers purpose, use case, and a configuration prerequisite. It does not explicitly state what happens when outputPath is omitted, but the schema already marks it optional. Given the low complexity and strong schema coverage, the description is nearly 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?

The input schema already describes both parameters (emailId in FOLDER::UID format, outputPath as optional file/directory). The description does not add much parameter-specific semantics beyond mentioning the .eml extension and the environment variable requirement. With 100% schema coverage, the baseline of 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 uses a specific verb ('Save') and resource ('full raw source (RFC822/.eml)') and clearly states the intended use case ('backup or migrating a message elsewhere'). This distinguishes it from sibling tools like save_attachment (which saves only attachments) and import_email (which brings messages in).

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 the tool ('Use for backup or migrating a message elsewhere') and provides a critical prerequisite (PROTONMAIL_ALLOW_FILE_DOWNLOAD_DIR configured, same as save_attachment). It does not explicitly state when not to use it or compare against alternatives, but the context is clear enough for an agent to select it appropriately.

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=true. The description does not add behavioral context such as side effects of syncBefore parameter (e.g., index refresh). With annotations present, the bar is lower, but the description provides no extra 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?

Two sentences, zero wasted words. The first sentence captures the core purpose; the second provides usage guidance and alternatives. Perfectly sized 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?

With no output schema, the description should explain what the tool returns (e.g., thread IDs, metadata). It does not describe the return format. However, given the usage guidelines and parameter details, it is adequate for basic invocation. 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 coverage is 100%, so the schema already documents all parameters. The description lists example categories but adds no semantic detail beyond the schema definitions. 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 action ('Find'), the resource ('email threads'), and the scope ('likely containing important document attachments...'). It distinguishes from siblings by noting it works without knowing exact sender or subject, and explicitly names an alternative tool for custom queries.

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 says when to use ('locate attachment-heavy threads by category without knowing exact sender or subject') and when not to ('Prefer search_indexed_emails with hasAttachment:true for custom attachment queries beyond the built-in categories').

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 only include destructiveHint=false, which is consistent. Description adds that flags can be added or removed, but doesn't detail other behavioral traits like rate limits, side effects, or behavior when flags already exist. Adequate but not rich.

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

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

Three sentences, no wasted words, front-loaded with purpose and usage guidelines. Highly 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 5 parameters and no output schema, the description provides usage context but omits details on dryRun (test mode) and acrossFolders scope. Return value not mentioned, but for a flag-modification tool, that may be acceptable. Moderate completeness.

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 only 20% (only messageId has a description). The tool description does not explain dryRun, flagsToAdd, flagsToRemove, or acrossFolders. This leaves agents without crucial parameter context. Fails to compensate for low schema coverage.

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 tool adds or removes IMAP flags across all messages in a thread using the Message-ID header. Distinguishes itself from sibling apply_thread_action by specifying when to use each.

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 says to use this tool when you have the raw Message-ID and want to flag an entire conversation, and to prefer apply_thread_action with specific actions when you have a local threadId. Provides clear decision 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 carries full burden. It discloses the live nature, the fact that no messages are fetched, and the speed/accuracy tradeoff of scanLimit. It does not explicitly mention read-only or side-effect-free behavior, but 'without fetching messages' strongly implies it. This adds meaningful context 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?

Three dense sentences: core function, use case, and explicit alternatives. Every sentence earns its place, with no redundancy or 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?

Given the simple two-parameter input and lack of output schema, the description provides return value names, use cases, alternatives, and performance tradeoffs. It is complete for a lightweight read-only stats 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 schema already covers both parameters completely, including defaults and the speed/accuracy tradeoff. The description adds no new parameter-level detail, so the baseline 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?

The description clearly states the tool returns live message count, unseen count, uidNext, and uidValidity for a single mailbox folder. It distinguishes itself from sibling tools by specifying it does so without fetching messages.

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 states when to use the tool (checking unread counts or folder health) and provides alternatives: count_messages for filtered queries and get_email_stats for aggregate summaries. This is strong when/when-not 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 indicate destructiveHint: true, so the bar is lower. The description adds useful behavioral context by noting the action is immediate and without review, and states a permission requirement. It doesn't detail the confirmation prompt for irreversible sends, but that is already partially covered by the destructive hint.

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 with no waste: function, usage trigger, and alternative/prerequisite. Information is front-loaded 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?

For a tool with 15 parameters, full schema documentation, and a destructive annotation, the description provides adequate context: what it does, when to use, what to prefer, and a key permission. It doesn't detail return values, but no output schema exists and the schema covers parameters thoroughly.

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 parameters are well documented there. The description adds minimal extra meaning by mentioning 'preserving original attachments' and 'optional note', but these are already reflected in schema parameters like includeAttachments and body/markdownBody. 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 'forward', the resource 'existing email', and key behaviors (preserving attachments, prepending optional note). It explicitly mentions the alternative create_forward_draft, distinguishing it from siblings.

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 when to use ('when you have an emailId and want to re-route the message without review') and when to prefer an alternative ('Prefer create_forward_draft to stage a forward for review first'). Also mentions a prerequisite (PROTONMAIL_ALLOW_SEND).

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=true, so the description is not required to reiterate safety. It adds context about ranking by urgency and filtering for action, but does not disclose deeper behavioral traits like indexing behavior or response format. With annotations covering the safety profile, a score of 3 is appropriate.

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 only three sentences, each with clear purpose: first sentence states the core function, second gives usage context, third references alternatives. No wasted words, front-loaded with the key 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 tool has 6 parameters and no output schema, the description provides adequate context: what the tool does, when to use it, a key parameter (pendingOn), and sibling distinctions. It does not explain the return format or pagination, but with high schema coverage and read-only annotation, it is sufficiently complete 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 coverage is 100%, so the schema already documents all parameters. The description adds a small extra note about the pendingOn filter ('to distinguish threads waiting on you vs. them'), which reinforces the schema. However, it does not significantly extend understanding beyond the parameter descriptions, 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 'Return mailbox threads ranked by reply urgency, filtered to those requiring action' with a specific verb and resource. It distinguishes from siblings by naming get_inbox_digest and get_threads, explaining their different scopes.

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 says 'Use for daily triage to surface what needs a response from you' and provides alternative tools with reasons: 'Prefer get_inbox_digest for a broader summary including stale items' and 'Prefer get_threads for an unranked thread list'.

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 the optional saveTo parameter that can write to disk, which implies side effects. However, the annotation declares readOnlyHint: true, suggesting no state change. This is a contradiction, as the tool can mutate disk state. Hence score 1 due to annotation 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?

Four sentences, front-loaded with purpose, every sentence adds essential information 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?

No output schema, but description hints at return values for saveTo case. It could be more explicit about the metadata structure, but overall sufficient given sibling tools and 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%, baseline 3. The description adds value by explaining the default for includeBase64, the need for environment variable for saveTo, and configuring inline size threshold. 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 'Fetch metadata for a specific email attachment and optionally return its base64-encoded content inline,' which is a specific verb+resource. It distinguishes itself from siblings like save_attachment and list_attachments by mentioning when to use the alternative.

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 'Use when you need to read or process attachment data in-memory' and 'Prefer save_attachment to write the file to disk instead,' providing clear context and alternative.

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 only declare readOnlyHint=true. The description adds substantial behavioral context: supported MIME types, HTML stripping, calendar summarization, a 512KB raw-content limit, and clear failure for non-text formats. This goes well beyond what annotations provide and does not contradict them.

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 the core purpose, followed by highly relevant details about size limits, format compatibility, and alternatives. Every sentence contributes meaningful information 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 tool has no output schema, but the description fully covers what it does, supported formats, limits, and failure modes. It also references sibling tools for fallback, making it self-sufficient for an agent to select and 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?

Schema description coverage is 100%; both emailId and attachmentId are already described with formats and sources. The description adds no further parameter-specific details, so the baseline score of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'Extract plain text from a text-like attachment' with a specific verb and resource. It further distinguishes itself from get_attachment_content by mentioning the base64 handling and size-limit differences, making its unique role clear.

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 when-to-use guidance: use for text-like attachments, when avoiding base64 encoding, and when the attachment exceeds the inline-base64 size limit. It also names alternatives (get_attachment_content or save_attachment) for non-text formats, and states the 512KB bound.

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=true, and the description adds useful behavioral context: the log is persistent, on-disk, spans sessions, and records write operations (sends, moves, deletes, drafts). It does not contradict the annotation. No mention of return format or ordering, but enough safety/behavior 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 concise sentences: purpose, use case, and explicit alternative. Front-loaded and every sentence earns its place 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 low-complexity read-only listing tool with readOnlyHint annotation and pagination params in schema, the description covers purpose, scope, persistence, and sibling differentiation. It does not describe return fields, but the absence of an output schema is partially mitigated by the clear 'entries' language and usage 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 description coverage is 50%: only offset has a description. The tool description does not elaborate on limit/offset, but offset is self-documented in the schema and limit has a default. This is adequate but adds no 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 opens with a specific verb and resource: 'Return recent entries from the persistent on-disk audit log of all write operations performed by this server.' It clearly distinguishes this from sibling tools by contrasting with get_logs for in-session debugging.

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 usage guidance is provided: use for reviewing mutations across sessions, and explicitly says 'Prefer get_logs for debugging in-session behavior and transient connection errors.' This names an alternative and gives exclusion 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?

Even though readOnlyHint=true already covers the read-only nature, the description reveals return contents (individual pass/fail per protocol), the server version and entrypoint path, and a subtle diagnostic warning about orphaned installs shadowing upgrades. This adds meaningful behavioral context 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 dense but every clause earns its place: purpose, use cases, return values, version-check guidance, and an alternative tool. The most actionable information is 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?

For a zero-parameter read-only diagnostic with no output schema, the description fully explains what it returns, why it matters, when to call it, and when not to. No critical information is missing.

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 and schema coverage is 100%, so there is nothing to document. Per the no-parameter baseline this is a 4; the description appropriately spends no space on parameters.

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 opens with a specific verb and resource: 'Check whether Proton Bridge SMTP and IMAP are reachable'. It clearly differentiates this diagnostic from the sibling run_doctor tool by name, so an agent can distinguish it without opening schemas.

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 when to use it: 'before sending or syncing, or when tools return connection errors.' It also names the alternative run_doctor and the condition for preferring that tool, leaving no ambiguity about 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?

Annotations declare readOnlyHint=true, and the description adds context that it reads from a local index (auto-refreshed if stale or empty) and reflects the last sync. This explains the data source and freshness behavior beyond the annotation. It also clarifies that results are frequency-derived, not from an address book, adding transparency about data provenance.

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 compact and front-loaded: it states the primary function, then usage, then data source caveats. Every sentence adds value, with 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?

Given the tool's simplicity (one optional param), the description covers purpose, usage, behavioral traits (read-only, auto-refresh), and caveats. It lacks explicit return format info, but no output schema exists and the tool is simple enough that this is not critical. It effectively compensates.

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% coverage with a single 'limit' parameter that has a default and description ('Maximum contacts to return'). The description does not add extra semantics beyond that, but since the schema is self-explanatory, a 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 what the tool does: returns the most frequently contacted email addresses ranked by interaction volume within the analytics sample window. It distinguishes itself from sibling tools like top_senders and search tools by specifying frequency-derived ranking and usage for identifying key correspondents.

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 says 'Use to identify key correspondents or to pre-populate recipient lists,' which provides clear context for when to use it. However, it does not explicitly state when NOT to use it or alternatives, though the note about not being a Proton contacts address book implicitly warns against using it for address book purposes.

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 readOnlyHint=true, but the description adds critical context: the tool only fetches locally saved drafts, not from the Proton server. 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 essential information with no redundancy 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?

For a simple read-only fetch tool with one parameter, the description fully covers purpose, usage context, and behavioral boundaries.

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 sole parameter draftId is described in the schema with 100% coverage; the description adds minimal extra value beyond listing sources, but overall it is adequate.

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 'Fetch' and the resource 'full content of a single locally saved draft', distinguishing it from sibling tools like list_drafts (which discover IDs) and list_remote_drafts (server drafts).

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 when to use (read/verify before sending/updating), recommends prior use of list_drafts, and directly contrasts with list_remote_drafts for server drafts.

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 include readOnlyHint: true, and the description adds significant context: 'Reads from the local index (auto-refreshed if stale or empty), not live IMAP — reflects the last sync.' This explains data source and staleness, going beyond the annotation to clarify behavioral nuances. 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?

The description is concise (five sentences) and front-loaded with the core purpose. Each sentence adds value: output definition, use cases, alternatives, and data source/behavior. No fluff or repetition.

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 tool has moderate complexity with 2 parameters (both documented), no output schema, and clear output description (top senders, busiest hours, volume by folder). The description explains what it returns and its data source, making it fairly complete. Minor gap: it does not specify sampling behavior details or formatting, but that is not critical for an analytics summary 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 100%—both 'days' and 'limit' have descriptions in the schema. The description does not explicitly explain these parameters, but since the schema already provides meaning, a baseline score of 3 is appropriate. No additional semantic value is added 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 tool's function: 'Generate sampled mailbox analytics including top senders, busiest hours of day, and volume breakdown by folder.' It specifies the resource (mailbox analytics) and the exact outputs, and distinguishes from sibling tools by naming alternatives (get_email_stats, get_volume_trends).

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 usage guidance is provided: 'Use for productivity insights and communication pattern analysis' and directs away from alternatives: 'Prefer get_email_stats for a fast aggregate count summary. Prefer get_volume_trends for per-day message volume history.' This clearly tells when to use this tool versus 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 provide readOnlyHint=true, setting the safety baseline. The description adds valuable behavioral context: the response includes a security block (dkim/spf/dmarc pass-fail, Proton's spam score/action, encryption metadata) for phishing triage. It also warns about not constructing the emailId manually. No contradictions with annotations.

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

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

The description is three tightly written sentences. The first states the action, the second gives usage context, and the third discloses the security block. Every sentence earns its place with zero redundant phrasing.

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 four parameters and no output schema, the description covers the key facets: the composite ID format, usage sequence, and the security block in the response. It could be more explicit about the full return structure (e.g., standard email fields), but 'full content' plus the detailed schema descriptions for preferHtml and showHeaders provide adequate 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%, so the baseline is 3. The description enhances the emailId parameter by explaining the format 'FOLDER::UID' and reinforcing that it must come from a prior tool call. This adds meaning beyond the schema's terse 'Composite email id from previous tool output.'

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 opens with a specific verb and resource: 'Fetch the full content of a single email using a composite emailId.' It also distinguishes itself from siblings by stating 'Use after get_emails or search_emails to read a specific message in full,' making the tool's 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?

Explicitly states when to use: 'Use after get_emails or search_emails to read a specific message in full.' It also gives a critical usage caveat: 'always use the id returned by a prior tool call; do not construct it manually.' It does not explicitly mention alternatives like get_emails_by_ids, but the 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?

Even though readOnlyHint is already present, the description adds meaningful behavioral context: it mentions 'live IMAP' (network-based, fresh data), default sort order and reversal, and a security warning about prompt-injection in snippets. This goes well beyond the annotation.

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 the core action, then usage guidance, then alternatives. No wasted words; every sentence carries operational 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?

Given the 7 parameters and rich sibling set, the description covers purpose, default behavior, pagination context, alternative tools, and a safety warning. It is fully sufficient for an agent to select and invoke this tool despite the lack 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?

The input schema has 100% coverage with detailed parameter descriptions, including sortByUid and includeSnippet warnings. The describe text repeats some schema info (e.g., sortByUid asc/desc) but does not add new parameter semantics beyond what the schema already provides.

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 starts with 'Fetch emails from a mailbox folder via live IMAP', using a specific verb and resource, and distinguishes itself from siblings like search_emails and search_indexed_emails by emphasizing 'live IMAP' and default sorting.

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 states when to use: 'Use to browse or paginate recent messages in a specific folder', and provides named alternatives: 'Prefer search_emails to filter by sender, subject, or date. Prefer search_indexed_emails for fast repeated queries...' This is model guideline clarity.

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 declare readOnlyHint=true, and the description adds valuable behavioral context beyond that: it discloses the batch failure semantics ('One failed id does not fail the whole batch — check each result's ok field') and the 25-item limit. This goes beyond the annotation's safety profile.

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?

Four sentences, each with a clear purpose: what it does, when to use, failure behavior, and alternative. No filler or repetition. The description is front-loaded with 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 the tool has no output schema and only readOnlyHint annotation, the description carries the burden of explaining the return envelope ('ok field'), usage context, and limitations. It covers use cases, exclusions, and error behavior, making it sufficient for an agent to select and 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?

Schema descriptions cover 100% of parameters, so baseline is 3. The description adds meaning by clarifying that emailIds are 'composite' and come from prior search/email results, which is not in the schema. It also reinforces the max 25 constraint. However, it does not add detail for preferHtml or maxBodyLength 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 uses a specific verb ('Fetch') and resource ('full content for multiple emails by composite id'), clearly distinguishing it from siblings like get_email_by_id (single) and search tools (search vs fetch by id). The phrase 'in one call (max 25)' adds precise 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?

Explicitly states when to use: 'Use to read a batch of specific messages from a prior get_emails/search_emails/search_indexed_emails result' and explicitly recommends an alternative: 'Prefer get_email_by_id for a single message.' This is clear, actionable 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?

Beyond the readOnlyHint annotation, the description discloses important behavioral traits: it reads from the local index rather than live IMAP, auto-refreshes if stale or empty, and may lag behind changes made in another client. It also explains the specific lag condition for unread counts, adding substantial 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 front-loaded with the core purpose, then gives usage guidance, then adds necessary caveats about data freshness. Every sentence earns its place; there is no redundant filler or repetition of schema 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 read-only tool with two optional parameters and no output schema, the description is complete: it explains what is returned, when to use it, what alternatives exist, and the data-source caveats that affect interpretation. No critical context is missing.

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 already fully describes both parameters with 100% coverage: 'days' as 'Trailing days window' and 'limit' as 'Maximum messages to sample.' The description does not add parameter-level meaning beyond this, so the baseline score of 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 opens with a specific verb and resource: 'Return aggregate mailbox statistics: folder message counts, total unread counts, and a brief analytics sample.' It clearly distinguishes itself from sibling tools by explicitly naming get_email_analytics and get_volume_trends as richer alternatives.

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 states exactly when to use this tool ('Use for a quick mailbox health overview') and explicitly directs users to alternatives: 'Prefer get_email_analytics for richer breakdowns... Prefer get_volume_trends for time-series daily volume data.' This is exemplary usage 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 declare readOnlyHint=true, so the description doesn't need to reinforce that. It adds valuable behavioral context: returns message and unseen counts, from live IMAP session, and warns about noselect folders. Could mention if data is cached, but 'live' implies fresh.

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 concise sentences with no extraneous information. Efficiently covers purpose, usage, and caveat.

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 no parameters and no output schema, the description fully explains the tool's return value, use cases, and relevant constraint (noselect folders). Sufficient for 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?

No parameters in schema; schema coverage is 100% trivially. Description does not need to add param info. Baseline 4 for zero parameters.

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 all mailbox folders with message counts and unseen counts from the live IMAP session.' It specifies the verb (return), resource (mailbox folders), and output details (counts). It also distinguishes from sibling tools like sync_folders 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?

Explicit guidance: 'Use to discover available folder names before targeting get_emails, move_email, or create_folder. Prefer sync_folders to force a fresh fetch when the folder list appears stale.' Provides clear when-to-use and alternative tool.

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 the tool as readOnlyHint=true, so the description does not need to reiterate safety. It adds value by explaining the selection criteria (age and pending-on state) and the syncBefore parameter refreshes the index. No contradictions with annotations.

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

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

The description is two concise sentences that front-load the purpose and usage guidance. Every sentence is necessary and informative, 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?

Given the tool has 4 optional parameters, no output schema, and annotations indicating a read-only operation, the description covers core functionality and usage context well. It lacks details on output format, but for a filter-and-list tool this is acceptable. The description is complete enough for effective 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 100%, so parameters are well-documented in the schema. The description adds extra context for 'syncBefore' ('Refresh the local mailbox index from IMAP') and 'pendingOn' enum values, enhancing understanding beyond the schema. Baseline 3 plus additional value yields 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 it returns threads overdue for follow-up based on age and pending-on state. It uses specific verbs and distinguishes itself from the sibling 'get_actionable_threads', 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?

Explicitly states when to use: 'looking for outbound messages you sent that haven't received a reply, or to surface stale inbound threads.' Also provides a clear alternative: 'Prefer get_actionable_threads for threads where someone is currently waiting on you.' This gives excellent guidance on 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?

Annotations already declare readOnlyHint=true, so the description carries a lower burden. It adds value by describing the output structure (unread counts, actionable/overdue threads) and mentions the syncBefore parameter behavior, supplementing annotations with useful 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?

Two sentences, no wasted words. First sentence describes what the tool returns, second gives usage guidance. Efficient 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?

Despite no output schema, the description adequately explains the return value (unread counts, top actionable threads, overdue threads) and the syncBefore parameter behavior. For a summary tool with three parameters, this is complete and 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter-specific meaning beyond what the schema already provides; it focuses on the tool's purpose and output.

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 returns a structured inbox summary with unread counts, top actionable threads, and overdue threads. It distinguishes itself from the sibling tool get_actionable_threads by positioning itself as the starting point for an inbox review.

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 provides usage guidance: 'Use as the starting point for an inbox review session' and recommends get_actionable_threads for deeper filtering, giving clear context for when to use this tool vs. 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 annotation readOnlyHint=true already communicates the read-only nature. The description adds useful behavioral context about what metadata is returned and the condition for using sync_emails first. It does not disclose potential error conditions or exact output format, but for a simple read-only metadata tool, this 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?

The description is three sentences, tightly structured, and front-loaded with the key output. Every sentence adds value: what it returns, when to use it, and what to do in a specific condition. 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 zero-parameter, read-only tool with no output schema, the description is complete. It covers the tool's function, provides usage context, and includes conditional logic for handling an empty or stale index. The context signals confirm its simplicity, and the description fully compensates for the lack 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?

The tool has zero parameters, and the schema is empty (100% coverage by default). The description doesn't need to explain parameters, and the baseline for zero-parameter tools is 4. It adds value by describing the returned metadata fields, which is more relevant than parameter info.

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: returning metadata about the local SQLite email index, listing specific fields (row count, last sync timestamp, schema version, per-folder coverage). It distinguishes itself from sibling tools like search_indexed_emails and sync_emails by positioning itself as a pre-query verification step.

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 usage guidance is provided: use to verify index freshness before querying with search_indexed_emails or get_threads, and call sync_emails first if the index is empty or stale. This clearly articulates when to use it and how it relates to 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?

Annotations already declare readOnlyHint true; description adds that it uses local index (potential staleness) and includes message counts, with a limit cap. 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 concise sentences front-loading purpose, usage, and alternative. 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 read-only tool with one parameter and no output schema, the description fully covers purpose, behavior, and usage 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 covers 100% of the single parameter limit, including cap and alternative suggestion. Description doesn't add new parameter info 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?

Clearly states it returns normalized Proton folders/labels from local index with counts. Explicitly distinguishes from get_folders for live 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?

Directs when to use: before filtering with search_indexed_emails or get_threads. Warns to prefer get_folders for live counts when index may be stale.

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 readOnlyHint annotation already marks it as read-only, and the description adds important context: logs are ephemeral and not persisted across restarts. This is valuable beyond the annotation, though it does not cover details like log rotation or memory 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 three sentences long, front-loaded with the main purpose, then the usage context, then a caveat and alternative. Every sentence earns its place 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?

For a simple read-only tool with no required parameters and no output schema, the description covers purpose, when to use it, the ephemeral nature of logs, and directs users to the persistent alternative. This is fully sufficient for an agent to select and invoke 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 description coverage is low (only offset has a description, level has an enum, limit just has a default). The description repeats the level enum values but provides no additional meaning for limit or offset, leaving a gap in parameter 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 opens with 'Return recent in-memory server log entries,' which is a specific verb+resource construction. It also explicitly distinguishes itself from get_audit_logs, making its purpose unmistakable.

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 clearly states when to use the tool ('Use to diagnose unexpected tool behavior or connection errors during the current session') and explicitly names an alternative for persistent logs ('use get_audit_logs').

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 enumerates the specific runtime state fields returned, adding behavioral details beyond the readOnlyHint annotation. It discloses that the tool is a read operation returning configuration and sync status, with no destructive effects.

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 sentences: the first lists the returned information, the second gives usage guidance. Every sentence is essential 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?

Despite no output schema, the description lists the categories of state returned, providing enough context for an agent to understand the output. No additional detail is needed for this simple zero-parameter 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 tool has no parameters, so the description cannot add parameter semantics. In this case a baseline of 4 is appropriate; no param info is needed.

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 uses a specific verb 'Return' and clearly identifies the resource 'server's current runtime state'. It enumerates the types of state information included, and distinguishes from the sibling tool get_connection_status.

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 when to use this tool ('understand how the server is configured and whether sync is actively running') and when to prefer an alternative ('Prefer get_connection_status for protocol reachability only'), providing clear decision 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?

The readOnlyHint annotation already covers the read-only nature, so the description adds little beyond 'saved' and 'by id'. It does not disclose behavior on missing IDs, error handling, or the exact return structure, but remains consistent with the annotation without 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 a single, clear sentence with no wasted words. It front-loads the verb and resource, making it concise and easy to parse.

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 one-parameter getter, the description covers the core purpose and scope. It does not mention what happens if the template is not found or the response format, but given the readOnlyHint and the simple nature, it is largely complete. Slightly brief but 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?

The input schema has full coverage for the single 'id' parameter, including a helpful description referencing create_template and list_templates. The tool description itself adds no parameter details, but the schema sufficiently documents it, meeting the baseline.

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 'Get' and the resource 'single saved email template by id', making it distinct from list_templates (plural) and create/delete operations. It is specific and immediately understandable.

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—fetching a template by its ID—but does not explicitly mention when to use it instead of alternatives like list_templates or render_template. No exclusions or alternate scenarios are provided, leaving usage to be inferred.

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=true. The description adds that it provides a summarized view and avoids reading all messages, implying lightweight read operation. No contradictions. Additional detail about non-modification could be included but not required.

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 efficient sentences: first states what it returns, second states usage context. No wasted words, 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?

For a simple read-only tool with one parameter and no output schema, the description sufficiently covers purpose, usage, and content. Could optionally specify that no pagination is needed but not required for completeness.

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 already has 100% description coverage for the single parameter (threadId). The tool description does not add extra detail beyond the schema, meeting the baseline for high coverage.

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 returns a summarized view of a single thread and lists specific components (inbound/outbound preview, attachments, recommended action). It differentiates from the sibling get_thread_by_id by indicating that tool provides full raw data.

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 recommends use for quick status checks without reading every message and directs to use get_thread_by_id for full raw data. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, so the description doesn't need to restate safety. However, it adds valuable context: the data comes from a 'local index' (implying cached or indexed state) and describes the return content in detail. This adds behavioral insight beyond the annotation.

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 the action and scope, second provides usage guidance. No fluff, front-loaded, every sentence serves a 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?

Despite lacking an output schema, the description fully explains what is returned (all messages, participants, labels, full metadata) and gives clear usage context. For a fetch tool with read-only annotations, this is 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% (both parameters documented), so baseline is 3. The description adds subtle value by specifying that 'threadId' comes from 'get_threads' (source context) and that 'folders' can scope the search. This enriches 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 states 'Fetch the complete normalized thread record from the local index' with specific resource and scope, and distinguishes from sibling 'get_thread_brief' by noting the alternative returns a summarized view. This provides clear purpose and differentiation.

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: 'Use when you need all messages in a thread. Prefer get_thread_brief for a summarized quick view that avoids returning the full message list.' This gives clear when-to-use and when-not-to-use, with a named alternative.

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=true, and the description adds useful behavioral context: grouping by subject/participants, reliance on 'the local mailbox index', and the limitation that only subject and participants are searched. There is no contradiction with annotations, and the added detail goes beyond the basic safety hint.

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 sentences, front-loaded with the primary purpose, and each sentence provides distinct, non-redundant information: the core function, the general usage context, and alternative tool recommendations. It is concise and well structured.

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 moderate complexity, read-only annotation, and the presence of siblings, the description covers purpose, field scope, usage alternatives, and prioritization guidance. No output schema exists, but the description sufficiently equips an agent to invoke the tool correctly without further clues.

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 parameters have schema descriptions, so the baseline is 3. The description adds meaningful semantic context by clarifying that body content is not searched, which supplements the query parameter description and helps agents avoid misusing the tool.

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 uses a specific verb ('Return'), a clear resource ('normalized email threads'), and explains the grouping behavior ('by subject and participants'). It effectively distinguishes the tool from siblings by explicitly naming search_indexed_emails, get_actionable_threads, and get_inbox_digest.

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 states when to use the tool ('Use to view mail as threads rather than individual messages'), when to use alternatives ('use search_indexed_emails to search body content'), and when to prefer two specific siblings for other needs (urgency, executive summary). This is explicit usage guidance.

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