proton-bridge-mcp
Server Quality Checklist
Latest release: v1.2.1
- Disambiguation5/5
Every tool targets a specific action and resource: read vs. view vs. save attachments are clearly separated by content type, single vs. bulk variants are explicitly described for one or many messages, and reply/draft/send/forward each serve distinct lifecycle stages. No two tools are functionally interchangeable without a clear scope difference.
Naming Consistency4/5The vast majority of tools follow a consistent verb_noun pattern (e.g., list_folders, read_message, create_draft), and all names are lowercase with underscores. Minor deviations like folder_status (noun_noun) and bulk_* prefixes (adverb_verb) introduce slight inconsistency, but the pattern remains predictable and readable.
Tool Count2/5At 34 tools, the server exceeds the 25-tool threshold and feels heavy for a mail client. The bulk/single pairs for mark, label, and remove_label add redundancy that could be consolidated with array parameters, and the attachment-specific tools (read, view, save, purge) could potentially be merged.
Completeness4/5The tool surface covers core email workflows comprehensively: reading, searching, sending, replying, drafting, labels, folders, attachments, and even security headers. Minor gaps include no permanent message deletion, no rename operation for folders/labels, and no dedicated 'list all messages' that doesn't rely on search filters, but these are workaroundable.
Average 4.1/5 across 34 of 34 tools scored. Lowest: 3.5/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 62 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
Tools from this server were used 6 times in the last 30 days.
This repository includes a glama.json configuration file.
This server has been verified by its author.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, and the description adds valuable behavioral details: returns uids + envelopes, newest first, and that include_locations reports other mailboxes each message appears in. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary action 'Search a folder'. It contains no filler and each sentence contributes meaningful information about filtering and return values.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core behavior and return format but omits guidance on when to prefer this tool over search_all_mail, the default result limit, and semantics for text/from/subject. Given the 11-parameter complexity and lack of output schema, it is serviceable but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 55%, leaving several parameters like text, from, subject, unread_only, and flagged_only without schema-level explanations. The description merely lists these filters without adding semantics. It does clarify since format and include_locations behavior, but this is marginal. Baseline 3 applies due to moderate coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search a folder' with a specific verb and resource, and lists the filter criteria. It distinguishes from search_all_mail by indicating folder scope, but does not explicitly name the sibling alternative, so it lacks full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like search_all_mail. 'Combine any of' is about combining filters, not tool selection. There is no mention of prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds 'The message stays where it is,' which clarifies that the tool does not move the message—information not contained in the annotations. This is a useful behavioral detail beyond the non-destructive and idempotent hints already provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, action front-loaded with no wasted words. Every word earns its place, and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core operation but lacks guidance on alternatives, prerequisites (e.g., label must exist), and potential error conditions. Given the tool has 5 parameters and no output schema, this is minimally adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so the schema already carries most parameter documentation. The description itself adds no parameter-specific meaning, staying at the baseline expected when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'Tag a message with an existing label' with a specific verb and resource. It distinguishes from related tools like move_to_folder by noting the message stays in place, 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.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as bulk_apply_label or remove_label. The note that the message stays provides a contrast to moving, but it does not tell the agent when to choose this over sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint false, destructiveHint false, and idempotentHint true, covering the safety profile. The description adds no extra behavioral context about side effects, confirmation needs, or error behavior beyond the action itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the action, and no redundant words. It is appropriately concise for the tool's straightforward functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters including dry_run and uidvalidity safety mechanisms, the description is quite terse. However, schema descriptions fill in those details, and the annotations provide safety context, making the description minimally acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 60% of parameters with descriptions (folder, dry_run, uidvalidity). The description restates the action enum but adds little for uid or the purpose of dry_run, though the schema fills those gaps adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool marks a single message with read/unread or star/unstar actions. The singular 'a message' distinguishes it from bulk_mark and other batch operations, and the action set differentiates it from label/move tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use this when you want to mark one message's state. However, it does not explicitly mention alternatives like bulk_mark for multiple messages or provide 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states the core action, which is already evident from the name and annotations. It does not disclose any additional behavioral traits such as folder naming conventions, side effects of moving, or the availability of dry_run. While annotations indicate readOnly=false and destructive=false, the description adds no context beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. The examples are parenthetical and do not clutter the main point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters with 60% schema coverage and no output schema, so the description carries a significant burden. It omits mention of dry_run and uidvalidity, which are important safety features, and does not describe return behavior. While the schema details these parameters individually, the overall tool context is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema lacks descriptions for uid and to_folder, but the description's example destination values ('Folders/<name>', 'Archive', 'Trash') provide useful context for the to_folder parameter. However, it does not clarify uid or source folder semantics, leaving some gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'move it into another folder', using the verb 'move' with the resource 'a message'. It also gives concrete destination examples ('Folders/<name>', 'Archive', 'Trash'), which differentiates it from bulk_move by implying single-message operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for filing a message into a folder but does not explicitly state when to prefer this over alternatives like bulk_move, nor does it mention any exclusions. No guidance is given for selecting this tool over sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the useful behavioral note that 'Messages stay where they are,' which is not captured by annotations. It also states 'one existing label,' implying the label must pre-exist. However, it does not explain behavior on invalid uids, missing labels, or return values. Given that annotations already cover readOnly/idempotent/destructive hints, the description contributes some but not rich additional context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the main action and a clarifying note about message placement. Every word earns its place; no unnecessary detail or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (5 parameters, no output schema), the description, combined with rich schema descriptions and safety annotations, is largely complete. It clarifies the core behavior (no move) and relies on the schema for parameter details. The only gap is the absence of any mention of return/result behavior, but that is not critical for a bulk action with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with detailed descriptions for all parameters (uids, label, folder, dry_run, uidvalidity). The description adds no extra parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: 'Apply one existing label to many messages.' It is specific (apply label, bulk scope) and differentiates from sibling tools like bulk_move by noting 'Messages stay where they are.' This clearly distinguishes it from move operations and from single-label tools like apply_label.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it is for bulk application of an existing label. However, it does not explicitly say when to use this tool versus alternatives (e.g., apply_label for single messages or bulk_move when moving is desired). The phrase 'Messages stay where they are' implies it is not a move, but there is no direct guidance or exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds minimal behavioral context beyond the bulk nature, and no contradiction with annotations is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that states purpose and cost benefit with zero wasted words. It is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema (5 params, 80% described) and annotations, the description is sufficiently complete for a simple bulk operation. It could mention dry_run or uidvalidity safety, but these are adequately captured in structured fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so the schema carries most parameter semantics. The description only reinforces action values (read/unread/starred) without adding new meaning beyond the enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool marks many messages read/unread/starred in one pass, using a specific verb and resource. It distinguishes from per-message operations by highlighting cost efficiency, but doesn't explicitly name the sibling 'mark' tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Far cheaper than one call per message' implies use for bulk marking and provides clear context. However, it lacks explicit exclusion guidance or a named alternative for single-message marking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive (destructiveHint: true, readOnlyHint: false), so the bar is lowered. The description adds useful context: messages keep their place and only lose the tags, clarifying that labels are removed rather than messages. However, the cryptic 'GATED' note and the lack of explanation about the 'confirmed' parameter or confirmation workflow leave behavioral gaps. This is comparable to the TDQS example where annotations covered safety and description added scoping but not full behavior, so a 3 is warranted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences plus a short fragment ('Labels only, GATED.'). Every part contributes meaning: the core action, the effect on messages, and a scope restriction. Even the cryptic 'GATED' is short and might hint at a gated operation. No wasted words, and the main purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters, one required, and no output schema. The description explains the primary action and effect, but it does not explain the confirmation workflow (the 'confirmed' parameter), when to use dry_run, or how this relates to single-label deletion. This is a destructive bulk operation, so the absence of guidance on using dry_run or confirming the deletion is a noticeable gap, making the description only minimally complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (labels and dry_run have descriptions, confirmed does not). The tool description does not add parameter-specific details beyond what the schema provides, aside from the general effect on messages. According to the baseline for good schema coverage, a 3 is appropriate; the description does not compensate for the undocumented 'confirmed' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes multiple labels in one pass, with the specific verb 'Delete' and resource 'labels'. It distinguishes from sibling tools like bulk_remove_label (which removes labels from messages) by clarifying that messages keep their place and only lose the tags, and it restricts scope to 'Labels only.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use when you want to delete several label definitions. It does not explicitly name alternatives (e.g., delete_label for single labels or bulk_remove_label for removing label associations), but the effect described ('Messages keep their place and lose the tags') implies a different use case than these siblings. This is clear context with no exclusions, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context beyond annotations: 'The messages stay where they are' clarifies that the operation is non-destructive to message location, and 'GATED, like remove_label' signals a confirmation step. However, the gating mechanism is not explained, and the annotations already convey idempotent, non-destructive, and mutating traits. The description complements annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: three short sentences, each serving a purpose (purpose, non-destructive clarification, gating warning). It is front-loaded with the core action and avoids filler or repetition. Excellent economy of words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given 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 does not fully explain the gating mechanism ('GATED') or the behavior of confirmed/uidvalidity, but these are partially covered by schema descriptions. The description is minimal and relies heavily on annotations and schema. It is sufficient for tool selection but not fully self-contained for invocation details, such as what precisely 'GATED' implies beyond the boolean parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is high (83%), so the baseline is 3. The description adds only marginal parameter context—'one label' and 'many messages' align with the label string and uids array—but it does not clarify confirmed, dry_run, or uidvalidity beyond what the schema already provides. It neither adds nor omits significant parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action clearly with a specific verb and resource: 'Take one label off many messages at once.' This distinguishes it from removing a single label (remove_label) and from adding labels (bulk_apply_label). The additional sentence 'The messages stay where they are' clarifies that this is not a move or delete operation, reinforcing the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case (bulk operation on many messages) but does not explicitly mention alternatives or exclusions. The phrase 'GATED, like remove_label' provides a hint about a confirmation requirement and points to a sibling tool for analogy, but it doesn't say when to choose this over bulk_apply_label or remove_label. No explicit 'when not to use' guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral context: it writes to a specific folder and never sends. This goes beyond what annotations state and helps avoid misuse. It does not mention side effects or return values, but the core behavior is well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each adding essential information: the action, the 'never sends' guarantee, and the reply-specific parameter guidance. No fluff or redundancy; it 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.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters and no output schema, the description is quite sparse. It lacks guidance on required parameters like 'to' and 'subject', attachment handling, or what the tool returns. While annotations provide some context, the description does not compensate for the low schema coverage, leaving the agent under-informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low at 25%, so the description must compensate. It explains the semantics of in_reply_to ('the original Message-ID') but does not clarify the other parameters (to, subject, body, cc, references, attach). Given the low coverage, the description is insufficient for full parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Write') and a clear resource ('a draft into the Proton Drafts folder'), and explicitly states 'Never sends', which distinguishes it from send-related siblings. It also mentions a specific use case for replies, further clarifying its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance for a specific scenario: 'For a reply, pass in_reply_to (the original Message-ID)'. It also implicitly indicates when not to use it via 'Never sends', but does not explicitly mention alternatives like 'update_draft' or 'send'. Still, the guidance is clear enough for most cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable context beyond annotations: it reveals the draft goes to Trash, is gated (likely requiring confirmation), and is non-permanent. This is useful despite destructiveHint being true. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the main action. The one-word sentence 'GATED' is cryptic but impactful, and each phrase earns its place. Could be slightly clearer but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple draft deletion tool, the description covers key behavior (to Trash, gated, non-permanent). The annotations provide destructive/read-only hints and schema covers parameters. No output schema exists, so return value details are not required. Adequate for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 60%, so many parameters already have descriptions. The tool description doesn't explain individual parameters, but the schema handles most of the burden. The word 'GATED' hints at the confirmed parameter but doesn't elaborate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool moves a draft to Trash, which is a specific verb and resource. It distinguishes itself from siblings like delete_label or purge_attachments by clarifying it's about drafts and non-permanent deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for soft-deleting drafts to trash, and 'Nothing here deletes permanently' suggests not to use it if permanent deletion is intended. However, it doesn't explicitly name alternatives or state when to use it over other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds scope ('full headers and body text') but does not disclose any additional behavioral traits such as error handling, rate limits, or message-not-found behavior. It adds some value beyond annotations but not rich context, consistent with a mid-range score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words, front-loaded with the verb and resource. Every word contributes meaning, including 'full', 'headers', 'body text', 'by uid', and 'within a folder'. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description's mention of 'headers and body text' communicates return content. It also clarifies the folder parameter. Given the tool's low complexity and strong readOnly annotation, the description is nearly complete, though it omits edge-case behavior (e.g., missing uid) and the uidvalidity safety mechanism is only in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (uid has no description, folder has default, uidvalidity has description). The description adds 'by uid within a folder', which provides basic meaning to uid and folder, but it does not explain uidvalidity or offer syntax details. Since the schema already covers folder and uidvalidity, the description adds marginal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read'), a specific resource ('message'), and explicit scope ('full headers and body text') with identifiers ('by uid within a folder'). This clearly distinguishes it from sibling tools like get_headers, which likely reads headers only, or search_mail, which finds messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this when you have a uid and want a single message's full content. It implies that get_headers would be for headers alone, but it does not explicitly name alternatives or state when not to use this tool. No exclusions are mentioned, so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description discloses the deduplication behavior (collapse duplicates by Message-ID) and that results report message locations. This adds meaningful behavioral context not present in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences that front-load the core function and then the usage context. Every word earns its place, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose and usage well, but given 8 parameters and no output schema, it leaves significant gaps. The lack of parameter descriptions for most fields and no detail on the result format beyond 'reporting where each message lives' makes it merely adequate, not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 38%, leaving most parameters (from, text, subject, unread_only, flagged_only) undocumented. The description does not compensate by explaining any parameter semantics, so agents are left without help for these inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Purpose is clearly stated with a specific verb and resource: 'Search every mailbox at once'. It also describes the distinguishing behavior of collapsing duplicates by Message-ID and reporting locations, which sets it apart from sibling search_mail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance: 'Use when you do not know which folder something is in.' This gives clear context but does not explicitly name alternatives or exclusion cases, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveness and mutability, but the description adds specific behavioral context: the draft is moved to Trash after sending, and sender/recipient checks re-run at send time. The term 'GATED' hints at restricted access, though it's vague. It doesn't explain the confirmation requirement, but that's partially covered by 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose and side effect, followed by a terse warning. Every word earns its place, with no fluff or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action and a key side effect, but omits important operational details: the need for 'confirmed' to actually send, the 'dry_run' option for previewing without side effects, and the UIDVALIDITY safety check. Without an output schema, these gaps could lead to incorrect usage if the agent relies solely on the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 60% of parameters with descriptions, leaving 'uid' and 'confirmed' undocumented. The description adds no parameter-specific meaning; it merely states the action. It fails to clarify the critical 'confirmed' flag or the 'dry_run' preview option, which are essential for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Send'), names the resource ('saved draft'), and states the outcome ('move it to Trash'). This clearly distinguishes it from siblings like 'send' or 'delete_draft' and leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'as written' implies use when no changes are needed, and 'then move it to Trash' signals when this tool is appropriate. It doesn't explicitly exclude alternatives, but the context is clear enough that an agent can infer when to use it versus other draft-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits beyond the annotations: that threading headers are preserved, the new version is saved before the old one is binned, and that omitting fields retains existing values. This adds meaningful context about what is destroyed (old version) and the order of operations, complementing the destructiveHint and idempotentHint annotations. It does not contradict any annotations, and it provides useful operational details without being overly verbose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each contributing distinct information: the core action, a key behavioral guarantee (carryover of threading headers, save-before-bin), and the update semantics (omission behavior). It is front-loaded with the main verb and resource, has no redundant words, and is efficiently structured for an AI agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 10 parameters and no output schema, the description covers the critical behavioral aspects: replacement, partial update, and destruction of the old version. It also integrates well with the annotations and existing schema descriptions for parameters like attach, folder, dry_run, uidvalidity, and from_address. Minor gaps exist (e.g., what happens if the draft does not exist, or how attachments are handled in the replacement), but the description is sufficiently complete for an agent to understand the tool's core function and side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, with some parameters (uid, to, cc, body, subject) lacking descriptions. The description helps by explaining the partial-update semantics for all fields ('Omit a field to keep what the draft already had'), which clarifies how parameters behave. However, it does not elaborate on individual parameter meanings or constraints (e.g., format of uid, what 'to' expects). The description adds moderate value but does not fully compensate for the missing parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action with a specific verb ('Replace') and resource ('a draft's contents'). It distinguishes itself from sibling tools like create_draft (creates a new draft) and delete_draft (removes a draft) by focusing on updating an existing draft's content. The mention of 'Threading headers are carried over' further specifies a unique aspect of this tool, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when you need to update an existing draft rather than create or send one) but does not explicitly state when to use it versus alternatives. It provides one usage guideline—'Omit a field to keep what the draft already had'—but lacks explicit exclusions or alternative tool references. Sibling tool names provide context, but the description itself gives no direct comparison guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructive, non-readOnly), the description discloses the confirmation gate and the need for confirmed=true, which is not implicit in the schema. It stops short of detailing other side effects, but the annotations cover the destructive nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the primary purpose, and contains zero filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, no output schema, and a destructive action, the description is somewhat minimal. It covers the core action and gating but leaves out guidance on constructing uid or the overall flow, relying heavily on the schema for the rest.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to 'to' (recipient) and 'confirmed' (gating), but a required parameter like 'uid' remains undescribed in both schema and description. Schema coverage is moderate (63%), and the description only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Forward an existing message to someone on demand') with a distinct verb and resource, setting it apart from sibling tools like send, reply, or create_draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit context that this is an on-demand action and includes a gating mechanism ('GATED like send: confirm recipient with the user, then call with confirmed=true'), but does not explicitly list exclusions or when to prefer alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds value by revealing that the tool returns parsed verdicts and Proton metadata, and that raw=true returns the unparsed header block. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the core purpose and then add the most important parameter behavior. Every sentence contributes meaningful information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description appropriately summarizes return content (headers, verdicts, metadata) and the raw mode. It could be more complete by clarifying uid/uidvalidity semantics, but for a read-only header tool this is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% (raw and folder have descriptions, but required uid and uidvalidity do not). The description does not compensate by explaining uid or uidvalidity; its only parameter-related addition, 'Pass raw=true for the unparsed header block,' largely restates the schema's description of raw.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches message headers plus SPF/DKIM/DMARC verdicts and Proton metadata for authentication judgment. This specific verb+resource combination distinguishes it from siblings like read_message or list_attachments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for judging whether a message is what it claims to be' provides a clear use case and implicitly positions this tool for message validation. It does not explicitly name alternatives or when-not-to-use, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral context: it searches across All Mail, groups messages by conversation, and highlights which ones carry documents. This explains the thread-reassembly behavior beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each earning its place. The first sentence is a crisp summary of the action, and the second provides essential background and a usage directive. There is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and the absence of an output schema, the description adequately conveys what the tool returns (all conversation messages with document flags). It could mention ordering or pagination, but the core scope and behavior are sufficiently covered for a read-only thread pull.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter already has a clear description (e.g., 'uid' is 'A message in the thread (its subject is used)'). The tool description adds no further parameter semantics beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Pull' and clearly states the resource: every message of a conversation from All Mail. It also distinguishes the tool from siblings by mentioning document-carrying messages and the IMAP/UI mismatch, which is unique to this thread-finding tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit context: run this before concluding what a thread needs, and explains the critical IMAP vs Proton UI distinction that makes this necessary. It doesn't name alternative tools for when not to use it, but the guidance is strong enough to signal when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals non-obvious stateful behavior: the first poll only records the mailbox position and returns nothing, and polling never marks messages as read. This goes beyond the annotations, which only indicate non-read-only, open-world, non-idempotent, non-destructive. The behavior about not replaying backlog is critical for correct usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and every sentence adds value (behavior on first poll, read side-effect). No filler or repetition. It is optimally concise for the amount of useful information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description states 'Messages that have arrived' but not the exact format. However, it covers the essential contexts: first poll behavior, statefulness, and read side-effects. The 'advance' parameter and its relation to ack_folder are in the schema, so the description doesn't need to repeat that. Overall, it's complete enough for a polling tool, just missing explicit output shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all three parameters (limit, folder, advance) with 100% coverage. The tool description adds no extra parameter-specific information. Per the rubric, the baseline is 3 when schema coverage is high, which is exactly the case here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool emits messages arriving since the last poll, with a specific initial behavior. It distinguishes itself from sibling tools like search_mail and get_headers by focusing on incremental new-message retrieval. The title confirms the action, and the description adds the crucial 'first poll emits nothing' detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for polling new mail and explains the first-call behavior, but it does not explicitly contrast with alternatives like search_mail or folder_status. There's no 'use this when' or 'instead of' guidance. While the context is clear, explicit alternatives or exclusions are missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds useful context about the scope ('all ephemeral saved attachments'), immediacy ('Immediately delete'), and the rationale (cleanup after reading). It 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the action statement, and includes a clear usage hint. Every word serves a purpose with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential purpose and usage context for a simple destructive tool with one optional parameter. It doesn't mention return values, but for a delete operation this is usually a success indication, and the lack of an output schema lowers the burden. The dry_run parameter is sufficiently covered by the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so a baseline of 3 applies. The description does not add any additional meaning about the dry_run parameter beyond what the schema already explains. The schema fully documents the parameter, so no deduction is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('delete') and clearly identifies the target ('all ephemeral saved attachments'). It distinguishes this tool from sibling deletion tools like delete_label or delete_draft by focusing on attachments and providing a specific usage scenario. The phrase 'Call after reading a saved file' adds further precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool ('Call after reading a saved file so nothing lingers on disk'), giving clear context. It doesn't name alternatives or explicitly state when not to use it, but the intended use case is well defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral details beyond annotations: it replies to the Reply-To address to keep alias mail masked, and clarifies that confirmed=true is required to send. These are not derivable from the readOnlyHint/destructiveHint annotations or the schema alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and every clause adds meaningful information. It avoids unnecessary repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, no output schema), the description covers the essential behavioral flow (draft vs send, Reply-To masking) without needing to restate schema fields. It omits edge cases like uidvalidity or attachment restrictions, but those are documented in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 91%, and the schema already explains draft, confirmed, quote, and other parameters. The description adds a brief note on the draft/confirmed relationship but does not materially augment parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Reply to one message with correct threading,' identifying the exact verb and resource. It distinguishes from siblings like reply_all by specifying 'one message' and from send/forward by the reply context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for replying to a single message with threading and explains the draft=true vs confirmed=true modes. It does not explicitly mention alternatives like reply_all for multiple recipients, but the context is sufficiently clear for an AI agent to select this tool appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations by disclosing that own addresses are removed from Cc and duplicates dropped. It also points to 'reply' for draft/confirmation rules, which is useful. However, it does not detail confirmation rules itself, relying on the sibling tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the core purpose and key behavioral nuance. No wasted words, and the cross-reference to 'reply' is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 11 parameters and no output schema, the description is reasonably complete because it references 'reply' for shared rules and the schema covers parameters. It could explain return values or edge cases, but the tool is a variant of 'reply', and the core behavior is clear. A more self-contained description would be better, but the sibling reference helps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 91%, so most parameters are already documented. The description mentions Cc behavior but does not add specific parameter semantics. The reference to 'reply' rules implies similar parameter behavior, but that is indirect. With high schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool replies to everyone on a message, distinguishing it from 'reply' (sender-only) and adding specific behavior about removing own addresses from Cc and dropping duplicates. This is a specific verb+resource with differentiation from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for replying to all recipients and references 'reply' for shared draft/confirmation rules, but does not explicitly state when to use this tool instead of alternatives like 'reply' or 'forward'. It provides context but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that files are EPHEMERAL by default and self-delete after the TTL, which is important behavioral context beyond the annotations' readOnlyHint and destructiveHint flags. This adds transparency about the tool's lifecycle behavior and potential surprise to users.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loaded with the primary action, followed by the intended use and the critical ephemeral behavior. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters and no output schema, the description covers the return value (path(s)) and a key behavioral caveat (self-deletion). It doesn't enumerate error scenarios, but the schema covers parameter-level details, making the description sufficient as an overview.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so most parameters already have descriptions. The tool description doesn't re-explain parameters, and it also doesn't clarify the undocumented uid and include_inline fields; however, these are reasonably inferable from their names and context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool writes attachment(s) to disk and returns the path(s), using a specific verb and resource. It also gives concrete use cases (images, scanned PDFs, anything not text-extractable) that distinguish it from siblings like read_attachment and view_attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use for images, scanned PDFs, or anything not text-extractable, giving a clear when-to-use signal. It does not name alternative tools but implies that text-extractable content is handled elsewhere, which is adequate guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and open-world behavior, but the description adds key behavioral context: the tool returns a viewable image and is the only way to see photos/scans under certain conditions. This goes beyond the annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, then return format, then constraint and alternative. Every sentence adds value with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations and schema, the description covers purpose and return type but omits parameter roles and any error/output behavior. The absence of an output schema and partial parameter descriptions leaves gaps, but the tool is simple and the core usage is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, but the description provides no additional parameter guidance. It does not explain the role of uid, folder, or uidvalidity, nor how 'filename' partial matching works. The description says 'image attachment' but not how to identify it, leaving the agent to rely on sparse schema hints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Look at an image attachment' and 'Returns it as a viewable image'. It explicitly distinguishes from read_attachment for text and PDFs, and the title adds image-specific context. This is a specific verb+resource with clear scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Directly says 'Images only, use read_attachment for text and PDFs,' naming the alternative tool and the condition for selection. Also mentions the scenario 'when the client cannot read local files,' providing clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint and destructiveHint, and the description adds the 'advance=false' semantic (no state advancement) and reinforces harmless repetition, offering context beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, fully front-loaded with the core action, and zero filler words. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter ack operation with no output schema, the description covers purpose, usage context, and idempotency behavior completely. No additional details are necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters documented. The description only reiterates the checkpoint source already described in the schema, adding no extra parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Commit') and resource ('checkpoint returned by poll_folder'), and distinguishes itself from siblings by referencing the exact source and advance=false behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly specifies when to use the tool (checkpoint from poll_folder with advance=false) and adds that repetition is harmless, which is useful usage guidance. However, it doesn't explicitly name alternatives or when-not conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds an important behavioral caveat about UIDVALIDITY generations, which is beyond what the readOnlyHint and openWorldHint annotations convey. It warns about the validity of UIDs across generations, giving the agent critical context for safe use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first states the primary output, the second provides an essential caveat. No filler or redundancy, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple status tool with one optional parameter and no output schema, the description adequately covers what the tool returns and the critical UIDVALIDITY caveat. It is complete enough for an agent to select and invoke the tool appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the single 'folder' parameter as defaulting to INBOX (100% coverage), so the description adds no additional parameter-level meaning. Baseline 3 applies because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies what the tool returns: message counts, UIDNEXT, and UIDVALIDITY for a folder. It lacks an explicit verb like 'get' or 'retrieve', but the resource and output are specific enough to distinguish it from siblings like poll_folder or list_folders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context: check UIDVALIDITY before acting on previously noted UIDs. It implies when to use this tool (before relying on stored UIDs) but does not explicitly mention alternative tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows it's a safe read. The description adds the 'Call this first' ordering and the purpose of learning names, but does not disclose additional behavioral details like pagination or response format. This is acceptable given annotation coverage, but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The first sentence states the core functionality, the second provides usage context. Each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple parameterless discovery tool with annotations, this is complete. It tells the agent what the tool returns (list of folders/labels) and why to use it (to learn exact names for filing/tagging). No output schema exists, so the description adequately covers what the agent needs to select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so the schema fully covers parameter semantics. Per the rubric, 0 params earns a baseline of 4. The description adds nothing parameter-related, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('all Proton folders and labels') and scope ('available over the Bridge'). It also distinguishes from siblings by being the discovery tool for names, unlike create_folder_or_label or delete_label which perform different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: 'Call this first' to learn exact folder/label names before filing and tagging. It does not explicitly name alternatives or exclude cases, but the instruction to call first is a useful usage guideline for a discovery tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant behavioral context beyond annotations: the required dry-run/confirmation gate is disclosed. This explains safe usage despite mutation (readOnlyHint=false) and non-destructive hint, making the tool's workflow transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with purpose and gate. 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.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The gated workflow is clear, and annotations cover safety profile. However, no output schema and no explanation of return values or to_folder semantics leave some ambiguity for a 6-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 67% of parameters. Description adds meaning for dry_run and confirmed via the gating phrase, but the required to_folder parameter remains undocumented in both schema and description. No clear explanation of how 'Trash' maps to to_folder.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb+resource+scope: 'File or Trash many messages at once.' This clearly distinguishes it from sibling tools like move_to_folder (singular) and bulk_apply_label (labels, not moves).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explicitly provides a two-step usage protocol: 'preview with dry_run=true, show the user, then call with confirmed=true.' It implies bulk use but does not explicitly state when to prefer singular alternatives like move_to_folder.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true), the description discloses a critical behavioral trait: 'Every message that carried it stays exactly where it is and simply loses the tag — no mail is deleted.' This adds important context that the destructive action is scoped to the label only, not the messages. The phrase 'GATED' also hints at a confirmation step, which aligns with the 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences front-load the purpose and then add necessary behavioral context. No filler or redundancy. Every sentence earns its place, including the 'GATED' marker which signals an important workflow constraint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is quite complete for a simple deletion tool: it explains the effect on messages, distinguishes labels from folders, and hints at gating. However, the 'GATED' term is ambiguous and the confirmed parameter is not explained, leaving some gaps. Still, it provides sufficient context 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes label and dry_run, covering 67% of parameters. The description adds context for the label parameter by clarifying labels vs. folders, but it does not explain the confirmed parameter or how dry_run interacts with the gated confirmation. Since coverage is moderate and the description does not fully compensate, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete a label outright' with a specific verb and resource. It also distinguishes this tool from folder operations by saying 'Labels only; folders are where messages live and are not deletable here.' This clearly differentiates from sibling tools like apply_label or bulk_delete_labels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use this tool: for deleting labels, not folders. It explicitly notes that folders are not deletable here, implying a boundary. However, it does not mention alternatives like bulk_delete_labels for batch operations, so it lacks explicit 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds behavioral context: supported formats (PDFs via pypdf, text/csv/json/ics/eml), inline text extraction, and a clear rule for binary types requiring save_attachment. This goes beyond annotation basics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose. No redundancy; every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only text extraction tool with 4 parameters and no output schema, the description conveys the key behavior, supported types, and the critical alternative for binaries. Some nuances like return format or uid semantics are left to the schema, but the core usage is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 75% of parameters with descriptions. The description does not clarify the remaining `uid` parameter or add syntax details. It provides no parameter-specific meaning beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb+resource: 'Extract an attachment's TEXT inline' clearly states the action and target. Lists supported formats and explicitly names save_attachment for binary types, distinguishing from the sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context ('Use for invoices, decks, reports') and an explicit exclusion: 'Binary/image types must use save_attachment instead.' Clearly directs when to use this tool vs alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint false, destructiveHint false), the description discloses an important side effect: the expunge against the label mailbox. It also mentions the need for confirmation or dry_run, which is critical behavioral information not captured by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, followed by a concise warning. Every word contributes, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description covers the key operational trait (expunge) and the required safety check. It could mention return values or error conditions, but the core usage context is sufficient given the simple operation and available sibling-tool context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes 4 of 6 parameters (67%), and the description adds context about the purpose of 'dry_run' and 'confirmed' by mentioning preview and confirmation. This supplements the schema for the two undocumented parameters (uid and confirmed) implicitly, though not explicitly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Take a label off a message') on a specific resource (a label on a message), and distinguishes it from related tools (e.g., apply_label, bulk_remove_label). The added detail that 'the message itself stays where it is' further clarifies that this is not a move or delete operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear operational context, explicitly warning that the operation ends in an expunge and advising to 'confirm it or preview with dry_run=true first.' It does not explicitly compare to alternatives, but the sibling tool names imply the scope (single label) and the guidance on safety is valuable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behaviors: that it only reports by default, that sending requires send=true, and that web links are never fetched. This adds safety context beyond the annotations, which already flag destructiveHint. It aligns with annotations and clarifies side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding value: purpose, default behavior, and a safety caveat. No waste, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, side-effect gating, and a safety guarantee, but does not describe the report format or the confirmation requirement for send, which is only in the schema. Given no output schema, this is a minor gap but overall adequate for a moderately complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers send, folder, and dry_run with descriptions, but uid, confirmed, and uidvalidity lack explanations. The description clarifies the send flag's role but does not compensate for the undocumented parameters, leaving some ambiguity for confirmed and uidvalidity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs 'Report' and 'send' with a clear resource (List-Unsubscribe header). It distinguishes from sibling tools like 'send' or 'reply' by focusing on unsubscribe semantics and explicitly notes that web links are never fetched.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when the tool reports only versus sends (unless send=true), and notes web links are never fetched, which guides usage. However, it does not explicitly mention alternatives or when not to use it, though the unique purpose is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructive annotation, the description discloses the critical safety protocol: the agent must obtain explicit user approval and set confirmed=true, and never call unattended. This is essential behavioral context not captured in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, and each sentence carries essential information. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter destructive tool with no output schema, the description focuses heavily on confirmation gating but omits other important aspects such as dry_run's safe preview use case, from_address alias handling, and attachment behavior. It is sufficient for avoiding misuse but incomplete for full operational understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers only 40% of parameters. The description adds meaning to 'confirmed' by tying it to the gating workflow, and references 'exact To/Subject/Body', but it does not compensate for other undocumented parameters like cc, references, in_reply_to, or attachment details. It provides some value but leaves gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Send a new email' with a specific verb and resource, distinguishing it from sibling tools like reply, forward, and send_draft. The gated confirmation requirement further clarifies its unique behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use: after showing the user the exact To/Subject/Body and receiving explicit yes, then calling with confirmed=true. Also states 'Never call unattended,' providing a clear exclusion. This is strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, and idempotentHint=true. The description adds behavioral context by noting 'it changes your folder and label structure' and the need for confirmation. This goes beyond annotations, though it doesn't detail edge cases like idempotency behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main purpose, then the gating instruction. No wasted words, well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential purpose and gating requirement. It omits explicit mention of dry_run in the text, but the schema covers that. For a simple creation tool with no output schema, this 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has descriptions for name and dry_run, but kind and confirmed lack descriptions. The description adds meaning for 'confirmed' by requiring confirmed=true after user confirmation, and clarifies that 'name' and 'type' (kind) must be verified. This compensates for the 50% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new label or folder' which is a specific verb+resource, and the sibling list shows other create actions like create_draft, so it distinguishes itself. It also mentions the gated nature, adding clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the gating condition: 'confirm the exact name and type with the user, then call with confirmed=true.' This tells the agent when to use it and what prerequisite steps are needed, including the confirmation requirement. It also implies dry_run can be used without confirmation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite readOnlyHint and openWorldHint annotations, the description adds valuable behavioral context: it separates document types and hides inline cid: images and PGP keys by default. This goes beyond what annotations alone communicate and is crucial for correct invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first front-loads the core purpose and key differentiation, the second provides a critical usage tip. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation with no output schema, the description covers purpose, when to use it, an alternative, and unique behavioral quirks. It is 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% (3/4 params documented). The description adds meaning for include_inline by explaining the default-hidden behavior and the document categorization, but does not elaborate on uid or folder beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('list') and resource ('a message's attachments'), and further distinguishes itself by separating real documents from inline cid: images and PGP keys. This clearly differentiates it from sibling tools like read_attachment or view_attachment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use it ('Call before claiming a message has no attachment') and names the alternative (read_message) that only shows body text and never reveals files. This is direct, actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ConsidusOld/proton-bridge-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server