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

Annotations already declare mutation (readOnlyHint=false), idempotency (idempotentHint=true), and non-destructiveness (destructiveHint=false). The description adds valuable provider-specific behavior: ProtonMail copies the message into a Labels/<name> folder, while Gmail and standard IMAP set a keyword flag. It stops short of covering error handling when the label is absent or permission requirements.

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

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

Two tight sentences: the first states the action, the second explains provider-dependent side effects. Every sentence is front-loaded and earns its place with no redundancy.

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

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

With no output schema and full schema coverage, the description plus annotations are nearly sufficient. It explains the action and provider behavior but omits what happens if the specified label does not exist (error vs. auto-create), which would be useful for a mutation tool.

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

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

Schema description coverage is 100%, so all four parameters are already well documented in the schema itself. The description adds no additional parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb 'Add' and resource 'label' scoped to 'an email', clearly distinguishing it from sibling tools like create_label, remove_label, and delete_label that operate on the label entity itself rather than applying a label to a message.

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

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

The description implies usage—use this when you want to attach a label to an email—but does not explicitly state when to choose it over alternatives like mark_email, move_email, or create_label, nor does it mention prerequisites such as the label already existing.

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

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

Goes well beyond the readOnlyHint=false/destructiveHint=false annotations: it discloses that a native confirmation dialog gates the write on macOS, that non-ICS attachments are written to local disk and linked in notes, that platform behavior differs (Calendar.app vs xdg-open), and it enumerates every return outcome including cancelled and timed_out.

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

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

One dense, front-loaded paragraph with no filler; the verb and platform lead, followed by extraction behavior, side effects, and return values. Slightly long, but every clause carries information an agent needs.

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

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

With 7 parameters and no output schema, the description compensates by enumerating the four possible return values and describing the side effects (attachment writes, confirmation dialog, platform dispatch). Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: it clarifies that confirm maps to a macOS-native dialog before the write, and that save_attachments covers any non-ICS attachment with local persistence plus note linking. alarm_minutes and calendar_name are left to the schema.

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

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

States a specific verb and resource — 'Add an email event to the local calendar' — and names the underlying platform (macOS Calendar.app / Linux via xdg-open). This clearly separates it from siblings like extract_calendar, analyze_email_for_scheduling, and create_reminder, which do not write to the calendar from an email.

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

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

The implicit context (an email containing event data) is conveyed through the extraction behavior, so an agent can infer when to reach for it. However, it never explicitly names alternatives such as extract_calendar or analyze_email_for_scheduling, nor states when NOT to use this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the no-side-effect profile is covered. The description usefully clarifies that the output is an analysis the agent interprets rather than an action, but says nothing about cost/latency (this appears to invoke analysis) or how the structured result should be consumed.

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

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

Three short sentences with the detection scope front-loaded, then routing guidance, then an explicit ordering rule. No filler or restatement of the tool name.

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

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

There is no output schema, and since the entire value of this tool is the structured analysis it returns, the description should sketch what that structure contains (event vs reminder signals, confidence). It also omits any relationship to the extract_calendar sibling, which is a real gap for a pre-step tool.

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

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

Schema description coverage is 100% and the required account/email_id plus optional mailbox are fully documented in the schema. The description adds no parameter-level meaning beyond 'an email', so the schema carries all semantic weight.

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

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

States a specific verb (analyze) and resource (email) plus the scope of detection: calendar events and/or reminder-worthy content. It is clearly distinguishable from the create-side siblings (add_to_calendar, create_reminder), but it never addresses the closely named sibling extract_calendar, leaving overlap ambiguity.

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

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

'Use this as the first step before creating any scheduling resource' gives explicit ordering guidance and names the downstream alternatives (add_to_calendar, create_reminder, both, neither). It stops short of saying when this analysis is unnecessary or how it differs from extract_calendar.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that 'send' transmits immediately, but says nothing about permissions, failure behavior, or whether preview/draft have side effects. Modest value beyond annotations.

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

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

Two tight, front-loaded sentences with no filler. The second sentence partially duplicates the action enum from the schema, which is a small redundancy, but overall the text is efficient.

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

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

With 100% schema coverage and annotations covering the safety profile, the description need not re-explain parameters or return values. It covers the three action modes, which is the key behavioral fork. Minor gaps remain around send/draft side effects but are acceptable given the structured data.

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

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

Schema description coverage is 100%, so the schema already documents account, template, variables, to, and the action enum. The description adds only the 'variable substitution' concept, which is largely redundant with the schema's own variable example. Baseline 3 is correct 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.

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

States a specific verb and resource ('Apply an email template with variable substitution'), which is clearer than the sibling send_email/save_draft by naming the template mechanism. It does not, however, explicitly contrast itself with those siblings, so an agent still infers the boundary.

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

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

The second sentence explains what each 'action' value does, which is mode-selection guidance. But it largely restates the enum already in the schema and gives no when-to-use-this-tool-vs-alternatives (e.g. apply_template+send vs send_email). Usage is implied, not stated.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds real value on top: it names delete as one of the destructive actions, discloses the 100-ID batching limit, and states that success/failure counts are returned, which hints at partial-failure behavior. It stops short of saying whether failures are atomic/rolled back or what auth is required.

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

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

Three short sentences, front-loaded with the core purpose, then supported actions, then limits and return shape. No redundant or filler language.

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

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

For a 5-param mutation tool with no output schema, the description covers actions, batching limits, and return summary, while annotations carry the destructive profile and the schema carries parameter detail. Minor gap: no statement about partial-failure/atomicity semantics or the destination requirement for 'move' (left to the schema).

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

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

Schema description coverage is 100% and the schema already documents every parameter, including the move-requires-destination rule and the UID array bounds. The description restates the action list and the 100 max without adding syntax or format meaning, so the baseline 3 applies.

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

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

States a specific verb (batch operation) and resource (multiple emails by UID list) and enumerates exactly which actions are supported. The 'bulk'/'multiple emails' framing cleanly separates it from the single-item siblings move_email, delete_email, and mark_email without needing to name them.

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

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

Batching semantics imply the use case (act on many UIDs in one call rather than looping single-item tools), and the max-100 cap signals a practical boundary. However, it never states when to prefer this over repeated single-email calls, nor any exclusions or prerequisites, so guidance remains implicit.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds a genuine side-effect disclosure beyond annotations: the scheduled item is removed from the queue and the associated draft is deleted, which is non-obvious and important. It stops short of stating reversibility or failure modes.

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

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

Two short sentences, front-loaded with the action and immediately followed by the destructive side effect. No filler or redundancy.

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

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

For a one-parameter destructive mutation with full annotation coverage and no output schema, the description supplies what matters most: the queue removal and draft deletion. It could be complete with a note on whether cancellation is permanent or error behavior, but the essentials are present.

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

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

Schema description coverage is 100% for the single schedule_id parameter, so the schema already documents it fully. The description adds no format, source, or constraint detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb ('Cancel') and resource ('scheduled email'), clearly distinguishing it from siblings like delete_email and list_scheduled. It does not explicitly name an alternative sibling by name, but the action is unambiguous.

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

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

The description gives no when-to-use context, prerequisites, or named alternatives. Usage is only implied by the tool name ('scheduled'), with no guidance on how it differs from delete_email or when a scheduled item cannot be cancelled.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond that: platform-specific behavior (macOS Privacy & Security → Calendars), the fact that it returns a granted status, and that it returns setup instructions on failure — useful for a diagnostic tool.

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

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

Three short sentences, front-loaded with the core purpose, followed by platform behavior and return content. No filler or restatement of the tool title.

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

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

With no output schema and no parameters, the description carries the full burden and does so: it describes the return value (granted status plus step-by-step fix instructions) and the platform caveat, leaving no gap an agent needs to call and interpret this correctly.

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

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

The tool takes no parameters, so the baseline is 4; there is nothing for the description to clarify beyond what the empty schema already implies.

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

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

States a specific verb+resource: checking whether the local calendar is accessible, and scopes it to the platform (macOS Calendar.app). This clearly separates it from other diagnostic siblings like check_health or check_clipboard_setup, which target different subsystems.

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

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

The description implies usage (diagnosing calendar access before attempting calendar operations) and mentions the privacy permission needed, but it never states explicitly when to call this versus alternatives such as list_calendars or extract_calendar, nor any when-not conditions.

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

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

Goes beyond the annotations by naming the concrete behaviors the diagnosis inspects and by disclosing that test_write=true performs a write/read/clear round-trip rather than a pure read. No mention of error modes, permission requirements, or what the diagnostic report contains, so it stops short of 5.

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

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

Two sentences, front-loaded with the purpose, then the one conditional behavior. Every clause carries information (the four inspected areas, the opt-in write path) and nothing is padding.

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

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

With no output schema and no annotation detail beyond the safety hints, the description should carry more of the result contract – what the diagnostic actually reports or what a failing check looks like. It names the inspected inputs but leaves the output shape entirely unstated.

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

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

Schema description coverage is 100%, so the schema already defines test_write as 'Write/read/clear a test string to verify the pipeline end-to-end'. The description restates that as a 'harmless clipboard round-trip', adding only the reassurance of harmlessness – a marginal increment over the structured field.

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

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

States a specific verb (diagnose) and a narrow resource (the clipboard integration for caught verification codes), then enumerates exactly what is inspected: platform tools, concealed-write support, [settings.verification] values, and the watcher prerequisite. This is clearly distinguishable from siblings like configure_verification or check_notification_setup.

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

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

Usage is only implied – the agent can infer this is the pre-flight/repair check for verification-code capture, and the description explains what test_write=true does, but it never says when to reach for this versus configure_verification or get_verification_code, nor any prerequisite condition for running it.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond them by itemizing what is actually inspected (connection health, quota, capabilities, cache size, coverage, hit ratio), which tells the agent this is a broad diagnostic probe rather than a narrow status read.

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

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

Two sentences with no filler, and the enumeration of checked dimensions is front-loaded before the purpose statement. Slightly dense but every clause earns its place.

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

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

For a single-optional-param, read-only diagnostic with no output schema, the description adequately conveys what areas are reported on. It would be marginally stronger if it said whether the check performs live network calls or reads cached state.

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

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

There is a single optional parameter and schema description coverage is 100%, with the schema stating 'Account name (checks all accounts if omitted)'. The description adds nothing about the parameter, so the baseline 3 applies since the schema carries the full burden.

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

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

The description gives a specific verb ('check') and enumerates the concrete resources inspected: connection health, quota, capabilities, cache size, coverage and hit ratio. That scope clearly separates it from siblings like get_email_status or get_watcher_status, though it never names an alternative explicitly.

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

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

'Useful for diagnosing issues' implies a diagnostic context but does not state when to prefer this tool over get_email_status, get_watcher_status or check_notification_setup, nor any exclusion conditions. Usage is implied rather than prescribed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond annotations by disclosing that it probes OS-level tool availability and returns setup instructions, but it stops short of characterizing the diagnostic result (pass/fail granularity, error modes) — no output schema exists, so this is a real gap.

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

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

Two sentences, zero waste, front-loaded with the primary action ('Diagnose desktop notification support') before the elaboration. Every clause earns its place.

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

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

For a zero-parameter, read-only diagnostic with no output schema, the description covers what it checks and where it applies. The one missing piece is what the caller gets back (per-platform pass/fail detail vs. free-form instructions), which matters more here because no output schema documents the return value.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It correctly implies the tool is platform-scoped and argument-free.

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

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

The description states a specific verb and resource ('Diagnose desktop notification support', 'Checks if required OS tools are available') plus the platform scope (macOS, Linux, Windows). It is clear on its own, but it does not name or contrast with neighboring tools such as test_notification, configure_alerts, or check_clipboard_setup, so an agent must infer the boundary itself.

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

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

Usage is implied rather than stated: the natural read is 'run this to diagnose whether notifications can work before trying test_notification', but the description never says when to call it versus those siblings or what to do with the result. There are no explicit exclusions or prerequisites.

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

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

With annotations only declaring readOnlyHint=false and destructiveHint=false, the description carries real added weight: changes apply immediately, the default is runtime-only, and omitting a field leaves it untouched (a partial-update contract). It does not address failure modes or whether a restart is ever required, keeping it short of a 5.

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

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

Three short sentences, front-loaded with the core action and then the persistence and partial-update rules. Every sentence carries a distinct, actionable fact with no filler.

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

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

For a six-parameter, all-optional mutation tool with no output schema, the description covers the essentials an agent needs: immediacy of effect, persistence control, and partial-update behavior. It is slightly thin on interaction effects (e.g., what happens to webhook_events when the URL is cleared) but adequate overall.

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

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

Schema description coverage is 100%, so the baseline is 3 regardless. The description nonetheless adds a genuine semantic rule not spelled out in the schema — "omit any field to leave it unchanged" — clarifying that all six optional parameters behave as a merge rather than a full overwrite, and it reinforces the save semantics.

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

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

The description opens with a specific verb and resource ("Update alert/notification settings"), clearly distinguishing this from read-oriented siblings like check_notification_setup and test_notification. It stops short of naming an alternative tool by name, so it does not reach the full sibling-differentiation credit.

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

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

It gives one concrete usage rule — "Use save=true to persist changes to the config file" — which tells the agent how to choose behavior. However, it never states when to reach for this tool versus configure_verification, check_notification_setup, or test_notification, so the routing guidance is only implied.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing that changes take effect immediately, that save=true persists to config.toml with a backup of the previous file, that enabled starts/stops the ambient catcher, and that the tool is available in read-only mode yet only writes config, never the mailbox. This gives the agent a full behavioral picture of a mutation with a rollback safety net.

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

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

Three tightly packed sentences, front-loaded with the primary action and effect, followed by persistence, read behavior, and scope caveats. Each sentence carries distinct, useful information with minimal waste.

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

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

For a 12-parameter mutation tool with no output schema, the description covers effect timing, persistence/backup, read mode, and scope boundaries, which is close to complete. It could still note the relationship to sibling configuration tools, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters, establishing the baseline of 3. The description reinforces the meaning of a couple of key params (save, enabled) but adds little semantic detail the schema does not already carry.

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

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

States a specific verb (Update) and resource ([settings.verification]) and conveys the domain (verification catching), which an agent can clearly separate from siblings like configure_alerts or get_verification_code. It does not explicitly name or contrast an alternative tool, so it stops short of the top band.

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

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

Gives concrete operating guidance: use save=true to persist, and omit every field to read the current configuration. It establishes clear usage context for the write-vs-read patterns but offers no when-not guidance or explicit routing to a sibling tool.

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

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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false). The description adds real behavioral context beyond that: ProtonMail stores it as a folder under Labels/, and for standard IMAP keywords the call is a no-op because labels are auto-created on first use — a critical 'this may do nothing' disclosure.

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

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

Three short sentences, front-loaded with the primary action and then the backend-specific behavior. Every sentence carries information; nothing is redundant with the title.

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

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

For a simple two-parameter creation tool with no output schema, the description covers the key ambiguity (per-backend behavior and the no-op case). It lacks only sibling routing guidance to be fully complete.

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

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

Schema coverage is 100%, and the schema itself documents both parameters including the '/' nesting convention and the list_accounts reference. The description adds no parameter-level meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Create a new label') and goes further by distinguishing the two backends it can act on. It does not, however, explicitly contrast itself with the sibling 'add_label' (apply) vs 'create_label' (define), so an agent must infer that boundary.

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

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

Usage is implied rather than stated. The No-op caveat for standard IMAP keywords hints at when this call is pointless, but there is no explicit guidance like 'use add_label to apply an existing label to a message' or prerequisites beyond the account param.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the safety and idempotency profile. The description adds useful context about nested folder syntax but does not describe what happens if the folder already exists, whether parent folders are auto-created, or any permission requirements.

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

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

Three short sentences, front-loaded with the core action, followed by syntax guidance and a helpful cross-reference. Every sentence earns its place with no redundancy.

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

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

For a simple creation tool with full schema coverage and relevant annotations, the description covers purpose, path syntax, and a useful sibling reference. A minor gap remains around conflict handling and whether parent directories are created automatically, but annotations mitigate the idempotency concern.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explicitly specifying the '/' separator for nested folders and giving an example ('Work/Projects'), which clarifies how the 'path' parameter can be structured.

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

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

States a specific verb ('Create') and resource ('mailbox (folder)'), and immediately clarifies that mailbox means folder. It distinguishes itself from siblings like list_mailboxes and delete_mailbox by explicitly naming the read-only alternative.

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

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

Points to list_mailboxes for checking existing folders, which is a clear contextual alternative. However, it does not explicitly state when not to use this tool or outline prerequisites (e.g., required permissions).

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

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

Adds real behavior beyond annotations: a native confirmation dialog appears before adding, and notes always get an appended deep link that reopens the source email. It does not state permission/authorization requirements or what happens if the Reminders list is missing, so it falls short of a full behavioral picture.

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

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

Four short sentences, each carrying a distinct load: what it does, the confirmation behavior, the notes side effect, and the routing precondition. Front-loaded with purpose and zero filler.

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

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

For a 9-parameter mutation tool with no output schema, the description covers purpose, side effects, and prerequisites, which is most of what an agent needs. It stops short of describing the result returned or list-not-found failure modes.

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

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

Schema description coverage is 100%, so all 9 parameters are already documented. The description mostly restates schema facts (notes auto-built, deep link appended, title defaults to subject) rather than adding new meaning, so baseline 3 applies.

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

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

States a specific verb (create), resource (reminder), target app (macOS Reminders.app), and source (an email). An agent can immediately distinguish it from list_reminders and analyze_email_for_scheduling.

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

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

Explicitly says when to use it ('action items, deadlines, and follow-up tasks extracted from emails') and names the gating alternative ('Use analyze_email_for_scheduling first'). This is a concrete when/when-not routing instruction.

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

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

Annotations already declare destructiveHint=true, but the description adds materially: the default is a recoverable move to Trash, permanent=true is irreversible (flagged with a warning glyph), and the target mailbox must be a real folder. It does not cover auth/permission needs or success return, keeping it below a 5.

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

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

Three short sentences, zero filler, with the default behavior stated first and the destructive escalation second. Every sentence carries information an agent needs to call the tool safely.

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

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

For a 4-parameter mutation with annotations and no output schema, the description covers reversibility, the destructive option, and the folder prerequisite. It is slightly thin on what a successful deletion returns and on account/emailId sourcing, but nothing critical to correct invocation is missing.

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

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

Schema coverage is 100%, so 3 is the baseline, but the description adds semantics not in the schema: the mailbox must be a real (non-virtual) folder, which explains why find_email_folder may be needed. It also reinforces the irreversible nature of the permanent flag beyond the schema's brief note.

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

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

States a specific verb and resource ("Delete an email") and immediately qualifies the operation's scope: default soft-delete to Trash versus permanent removal. This distinguishes it from siblings like delete_label, delete_mailbox, and bulk_action, which operate on different resources.

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

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

Gives a concrete prerequisite and routes the agent to a sibling tool ("Use find_email_folder first if the email was found in a virtual folder") and explains the condition that selects the permanent path. It does not mention when to prefer bulk_action for multiple messages, so it stops short of full alternative coverage.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so safety is covered. The description adds real value beyond them by disclosing provider-dependent behavior — that on IMAP the operation effectively fails and a different tool must be used. It doesn't state whether the delete is reversible or what happens to emails bearing the label, which keeps it out of 5 territory.

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

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

Three short sentences, zero waste, with the primary action front-loaded and the provider caveat following immediately. Every sentence earns its place.

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

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

For a two-param destructor with full schema coverage, no output schema, and annotations carrying the safety profile, the description covers everything an agent needs: what it does, the provider dependency, and the fallback. Nothing essential is missing.

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

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

Schema coverage is 100% with both params (name, account) documented, so the schema does the heavy lifting. The description adds nothing about syntax, naming constraints, or the account param. Baseline 3 is appropriate.

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

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

States a specific verb (delete) and resource (label), and explicitly distinguishes the two backends: ProtonMail deletes the label folder, standard IMAP keywords can't be deleted server-wide. An agent can separate this from add_label/create_label/remove_label without opening any schema.

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

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

Explicitly names the alternative (remove_label on individual emails) and the exact condition that routes to it (standard IMAP keywords, no server-wide delete). This is a genuine when-not clause, not just implied context.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds material context beyond that: the deletion is permanent, irreversible, and destroys all contained emails. It stops short of stating permission requirements or failure behavior for non-empty mailboxes.

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

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

Two tight sentences with the destructive warning front-loaded and the precondition second. Every clause carries weight and nothing is redundant.

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

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

For a two-parameter mutation with annotations covering destructiveness and no output schema, the description supplies the irreversibility and content-loss facts an agent needs before calling. Missing only auth/permission expectations and what happens on a non-empty or invalid path.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the warning on 'path'. The description only echoes the folder-path concept and the list_mailboxes source of truth, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (delete) and resource (mailbox) plus scope ('ALL its contents'), which cleanly separates it from delete_email, delete_label, and rename_mailbox. The permanence qualifier makes the operation unmistakable.

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

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

It gives one procedural pointer — verify the folder path with list_mailboxes first — which is genuinely useful. However, it offers no guidance on when to choose this over delete_email or bulk_action, and no explicit when-not conditions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral context: base64-encoded return, a ≤5MB size limit, and the unavailability of saveToDownloadDir. It does not explain what happens for files larger than 5MB, so it is strong but not exhaustive.

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

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

Three tight sentences, front-loaded with the primary action. Each sentence contributes unique operational information: the get_email prerequisite, the return format and size limit, and the disabled save option.

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

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

For a 7-parameter read-only tool with no output schema, the description supplies the key context an agent needs: how to discover attachments, what the return value looks like, the size limit, and the disabled save directory. It omits the behavior for attachments larger than 5MB, leaving a minor gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds decision-relevant meaning beyond the schema by highlighting partId precedence for duplicate filenames and inline cid images, and by declaring saveToDownloadDir unavailable, which directly affects parameter usage.

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

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

States a specific verb ('Download') and resource ('email attachment'), and clarifies the two selection mechanisms ('filename or part id'). It also points to get_email for discovering attachments, which implicitly separates its role from the retrieval tool.

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

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

Explicitly instructs the agent to first use get_email, and advises using partId for duplicate filenames and inline cid images. It also states that saveToDownloadDir is unavailable, giving clear when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value by disclosing the return shape (time, location, attendees, status), but it says nothing about behavior when no calendar part exists or how parsing failures surface.

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

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

Two tight sentences: the first states what is extracted and from where, the second lists the returned fields. Nothing is redundant and the essential information is front-loaded.

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

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

For a read-only, three-parameter tool with full schema coverage and annotations covering safety, the description is nearly complete: it names the source and the returned fields. It only omits behavior for emails without an ICS part, which is a minor gap given the low complexity.

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

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

Schema description coverage is 100%, with account, mailbox, and email_id all documented in the schema itself, so the baseline is 3. The description adds no parameter-level meaning beyond what the schema already provides.

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

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

The description states a specific verb (Extract) and resource (calendar events / ICS from an email), and the parenthetical format hint (ICS/iCalendar) pins down what is being parsed. It implicitly distinguishes itself from extract_contacts by resource type, though it never names that near-parallel sibling to route the agent explicitly.

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

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

There is no guidance on when to use this tool versus alternatives such as get_email, extract_contacts, or add_to_calendar, nor any stated preconditions (e.g. the email must actually contain an ICS part). The 'from an email' phrasing only weakly implies the required email_id context.

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

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

Annotations already declare the read-only, non-destructive safety profile, so the description's job is to add operational context — and it does: results are de-duplicated and sorted by frequency descending, drawn from recent email headers. It omits how contacts are identified (name vs. address) and any result-size behavior, which keeps it out of the 5 band.

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

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

Three short sentences, zero filler, with the core action front-loaded and the return-ordering detail placed second. Every sentence earns its place.

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

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

For a no-output-schema read tool with full annotation and schema coverage, the description supplies the essential missing pieces: output ordering, de-duplication, and the source of contacts. A note on whether contacts include display names, or how many results to expect for a given limit, would fully close the gap.

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

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

Schema description coverage is 100%, including defaults and bounds for limit, account, and mailbox, so the schema carries the parameter burden. The description only implies the 'recent' window that limit controls, adding no syntax or format detail beyond the schema — the correct baseline is 3.

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

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

States a specific verb and resource ('Extract unique contacts from recent email headers'), and the uniqueness/recency scope distinguishes it from every sibling in the list, none of which touches contact extraction. An agent can immediately tell what this does.

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

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

Gives a clear use context ('finding frequent correspondents or building an address book'), which tells the agent when this tool is the right pick. It stops short of naming any alternative or a when-not condition, so it doesn't reach the top band.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuine behavioral context beyond that: it returns only the FIRST real folder path, that path is meant as sourceMailbox, and on label-based servers the message may live in other folders too. This caveat about incomplete results is valuable.

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

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

Three sentences, front-loaded with purpose and the precondition, then the return semantics. Every sentence earns its place; slightly dense but no waste.

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

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

No output schema exists, and the description compensates by describing what is returned (first real folder path) and its intended use as sourceMailbox, plus the label-server caveat. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description goes beyond the schema by explaining the role of sourceMailbox ('where the email is currently visible' in a virtual folder) and tying the returned value back to that parameter, adding real semantic linkage.

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

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

States a specific verb and resource ('Find a real mailbox folder an email belongs to') and explicitly contrasts 'real' folders against 'virtual' ones. This is distinguishable from siblings like list_mailboxes and list_labels without opening any schema.

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

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

Explicitly names the triggering condition ('when the email was found in a virtual folder') and the dependent siblings ('Required before move_email or delete_email'). An agent knows exactly when to call this instead of acting directly.

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

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

Annotations cover safety (destructiveHint=false, readOnlyHint=false, openWorldHint=true), so the description correctly focuses on mechanics: how the original is quoted, attachment re-attachment, and the html flag's effect. It omits any delivery-failure or rate-limit context but adds substantive transformation details beyond annotations.

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

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

Three tight sentences, front-loaded with the core action, then the transformation rule, then the html opt-in. No filler or redundancy.

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

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

Covers the key behavioral surprises (quote wrapping, attachment default, html toggle) that an agent couldn't infer from the name alone. No output schema exists, but this tool realistically returns only send status, and no usage exclusions are stated — a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including html and includeAttachments. The description reinforces html and includeAttachments semantics but adds no format/syntax guidance beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb (Forward) and resource (email) with the key transformation described — original converted to quoted text with attachments re-attached. Clearly distinguishable from siblings like send_email (new message) and reply_email (to original sender).

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

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

The description implicitly signals when to use this over send_email/reply_email by describing forwarding semantics, but never explicitly names alternatives or states when-not-to-use. Guidance is implied through behavior rather than stated.

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

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

Goes well beyond the readOnlyHint/destructiveHint annotations: it discloses the IMAP BODY.PEEK mechanism, that the email is NOT marked seen, the 10000-char cap with the maxLength=0 escape, and the derived 'Bulk:' line with unsubscribe URI. These are exactly the side-effects and output quirks an agent needs.

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

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

Front-loaded with purpose and the non-destructive guarantee, then parameter guidance, then the Bulk note. Dense but each sentence carries information; only the final Bulk/marketing line is somewhat peripheral.

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

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

With no output schema, the description carries the return-shape burden and does so: it explains body formats, truncation behaviour and the remaining-characters hint, and the Bulk header derivation. An agent can call this correctly and interpret the result without further docs.

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

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

Schema description coverage is 100%, so the 3 baseline applies, but the description adds real meaning: what 'stripped' actually removes (quoted replies and signatures), what 'text' converts to (HTML with markdown links), and that maxLength=0 means unlimited. It enriches semantics beyond the enum labels.

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

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

States a specific verb and resource ('Get the full content of a specific email by ID'), which cleanly separates it from list_emails/get_emails (plural, summary) and get_thread (whole conversation). The scope word 'full' signals single-message retrieval.

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

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

It clarifies when to set markRead=true and how format choices map to intent, which is genuine usage guidance. But it never names an alternative sibling (e.g. get_thread for a conversation, get_emails for summaries), so the agent must infer when this tool is the right pick versus its neighbours.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds genuinely useful behavior beyond them: it explicitly states emails are NOT marked as seen, and it explains the default text format strips HTML for compact AI-friendly output. This preempts the common concern that reading mail mutates read state.

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

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

Four sentences, each earning its place, with the core purpose (batch fetch, max 20) front-loaded. No filler or repetition.

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

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

For a batch-read tool with safety fully covered by annotations and no output schema, the description covers the essentials: batch cap, format default, side-effect behavior, and the newsletter/automated markers returned per message. Return-shape details are reasonably signaled.

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

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

Schema description coverage is 100%, so ids, format, account, mailbox, and maxLength are all already documented. The description restates the max-20 cap and the text default, adding only the 'AI-friendly' rationale, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Fetch the full content of multiple emails in a single call') and quantifies the batch limit (max 20). It explicitly positions itself against the sibling get_email, so an agent can distinguish batch vs. single fetch without opening either schema.

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

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

Names the alternative ('More efficient than calling get_email repeatedly') and the condition that selects this tool ('when triaging or summarising several emails'). The 'Does NOT mark emails as seen' line implicitly redirects state-changing intent to mark_email, giving the agent clear routing guidance.

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

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

Annotations already declare readOnlyHint=true/destructiveHint=false, so the safety profile is covered. The description adds real value by disclosing the returned content (volume, top senders, trends, read/flagged counts), which is important since no output schema exists; it could add a bit more on period/default behavior.

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

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

Two tight sentences: purpose first, returned metrics second. No filler, well front-loaded.

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

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

For a read-only analytics tool with annotations covering safety and a fully documented schema, the description is nearly complete; enumerating return content compensates for the absent output schema. Only minor gaps (period default, response format) remain, which the schema largely covers.

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

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

Schema description coverage is 100% (account, mailbox with default, period enum all documented), so the baseline is 3. The description adds no parameter-level detail such as period semantics or default scope beyond what the schema already states.

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

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

States a specific verb+resource ('Get email statistics and analytics for a mailbox') and enumerates the metrics returned (volume, top senders, daily trends, read/flagged counts). No sibling tool provides statistics/analytics, so it is unambiguously differentiated from the operational email tools.

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

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

Usage is implied by the clear purpose (fetch analytics for a mailbox) but the description offers no explicit when-to-use guidance, prerequisites, or reference to alternatives. There is no direct stats sibling to route against, so the omission is mild but real.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description reinforces it with 'Does NOT mark the email as seen' and adds cost context ('Much cheaper than get_email'). It discloses the no-side-effect trait clearly, though it stops short of describing caching, consistency, or rate behavior.

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

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

Three short sentences, each earning its place: what it returns, why it beats get_email, and the no-side-effect guarantee. Front-loaded with the core purpose.

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

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

For a read-only status tool with full schema coverage and an output schema, the description covers everything an agent needs: what state is returned, when to prefer it, and that it has no marking side effect. No material gap remains.

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

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

Schema coverage is 100%, so account, emailId, and mailbox are already documented in the schema. The description adds no syntax or semantics beyond that, which matches the baseline 3 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.

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

States a specific verb and resource ('Get the current read/flag/label state of an email') and explicitly scopes what it does not do ('without fetching its body'). It cleanly distinguishes itself from siblings get_email and mark_email by naming both.

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

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

Names the alternative (get_email) with the selection condition ('when you only need to check whether an email is unread, flagged, or which labels it has'), and adds a second use case (confirming a mark_email result). When-to-use is explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful content disclosure (preset, rules, custom instructions) but says nothing about auth requirements, whether the config is cached, or how defaults are represented when no config exists.

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

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

One sentence, zero filler, with the resource front-loaded before the payload enumeration. Nothing could be removed without losing information.

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

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

For a zero-parameter read tool with no output schema, the description does the important work of naming what comes back (preset, rules, custom instructions). It is adequate, though it does not describe the shape or defaults of that returned configuration.

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

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

The tool takes zero parameters, so the baseline is 4 per the rubric. There is no parameter syntax the description needs to explain, and it correctly avoids inventing any.

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

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

States a specific verb ('Get') and resource ('AI hooks configuration') and enumerates the payload ('preset, rules, and custom instructions'). No sibling tool overlaps with hooks configuration, so the lack of explicit sibling differentiation is not a real gap, but the description stops short of the crispness a 5 requires.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no alternatives named. An agent can infer that this reads the hooks config, but the description provides no routing logic whatsoever.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds genuinely non-obvious behavior on top: 'Does NOT mark emails as seen,' per-body truncation at 5000 chars with a remaining-character hint, and a Bulk line flagging list/machine-generated mail. That is real behavioral context beyond the structured fields.

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

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

It is dense but front-loaded: purpose first, then the non-mutation guarantee, then format/limit/ordering semantics, then the prerequisite. Every sentence carries information, though the format explanation is packed tightly enough that a reader must parse carefully.

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

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

With no output schema and six parameters, the description still covers what comes back (all related messages, truncated bodies, Bulk annotations) and the ordering/format knobs an agent needs. Nothing required to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further: it clarifies that 'text' converts HTML with markdown links, that stripped removes quoted replies, that maxLength 0 means unlimited, and exactly how newestFirst alters per-message rendering. Only mailbox semantics are left entirely to the schema.

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

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

The description states a specific verb and resource ('Reconstruct a full email conversation thread') plus the mechanism (following References and In-Reply-To headers), which is unique among siblings like get_email and get_emails. An agent can distinguish this thread-reconstruction tool from single-message fetchers without opening any schema.

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

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

It gives an explicit prerequisite ('Use get_email first to obtain the message_id') and a situational cue for newestFirst ('Ideal for AI triage of long threads'). It does not explicitly state when to prefer get_email or get_emails over this tool, so it stops short of full alternative routing.

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

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

The annotations (readOnlyHint=false, destructiveHint=false) leave the non-read-only side effect unexplained, and the description fills that gap: copy_to_clipboard writes to the user's clipboard, is concealed from clipboard managers, and is auto-cleared. It also discloses latency expectations (max 45s wait, ~1s with watcher) and retry semantics. It doesn't mention auth/permission requirements, so not a full 5.

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

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

The core purpose leads the first sentence and each following sentence carries operational information (waiting, retry, watcher, clipboard). The closing sentence about the code being returned 'by design' is marginally redundant given the output schema exists, which keeps it from a perfect score.

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

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

For a five-parameter, zero-required tool with full schema coverage and an output schema, the description covers timing, retry, performance modes, side effects, and result format adequately. The one thin spot is that it references '[settings.watcher]' without directing the agent to the related configuration sibling.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining clipboards concealment and auto-clearing for copy_to_clipboard, plus the retry meaning of wait_seconds. It adds real semantic value rather than merely restating schema text, though account/mailbox/lookback_minutes get no extra description.

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

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

The description states a specific verb and resource ('Find the newest verification code (OTP/2FA) or sign-in magic link in recent mail') and even names the detection method. This is clearly distinct from generic siblings like search_emails, get_email, or get_emails, so an agent can route to it without opening a schema.

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

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

It gives concrete operating conditions: use wait_seconds for mail still in flight, simply call again if nothing arrives, and it contrasts polling vs. watcher-enabled behavior (~1 second hits). What's missing is an explicit pointer to a sibling (e.g., configure_verification for watcher setup) or a statement of when NOT to use this tool, so it stops short of 5.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so safety is covered externally. The description adds that the status concerns IMAP IDLE watcher connections and recent activity, but says nothing about return format, whether connections may be actively reconnecting, or what 'activity' includes. Modest added value over annotations.

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

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

A single, front-loaded sentence with no redundancy. Every word earns its place.

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

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

For a zero-param read-only status tool without an output schema, the description is adequate but thin. It does not describe what the returned status contains, which matters more when there is no output schema to fall back on.

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

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

Zero parameters, so per the rubric this is a baseline 4. The schema is trivially empty and the description does not need to document any inputs.

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

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

States a specific verb (get) and resource (status of IMAP IDLE watcher connections) with added scope 'recent activity'. However, it does not differentiate itself from the many other status/health siblings (get_email_status, check_health), leaving some ambiguity about when this tool is the right one.

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

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

No guidance on when to use this versus get_email_status or check_health. The sibling set is large and includes several 'status' tools, so the absence of any routing guidance is a real gap.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered and the description doesn't contradict it. It adds the useful framing that this is a discovery/prerequisite call, but says nothing about behavior when no accounts are configured or the shape/multiplicity of results.

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

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

Two short sentences, zero filler, with the action front-loaded and the usage instruction immediately following. Every clause earns its place.

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

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

For a trivial zero-parameter list tool with no output schema, the description covers what it does and when to call it. It could mention what a returned entry looks like, but that gap is minor given the simplicity of the tool.

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

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

The tool takes zero parameters, so the baseline is 4 and there are no parameter semantics for the description to clarify. Nothing is missing on this dimension.

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

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

States a specific verb and resource ('List all configured email accounts'), which is a distinct concept from the sibling list_mailboxes/list_labels tools. It doesn't explicitly contrast itself with those siblings, but the resource noun is unambiguous.

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

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

Explicitly prescribes ordering and intent: 'Call this first to discover available account names for use with other tools.' An agent knows exactly when to reach for this tool relative to every other tool in the set.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the platform scope note, which is beyond the annotations, but says nothing about empty-result behavior or ordering.

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

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

Two tight sentences with zero waste. The core purpose is front-loaded and the follow-up sentence is actionable rather than filler.

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

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

For a parameterless read tool with a trivial schema and no output schema, the description covers what is listed and how the result is consumed. Only minor gaps remain, such as return ordering or empty-result behavior.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description cannot add parameter meaning that does not exist.

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

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

States a specific verb+resource ('List all available local calendars') and scopes it with platform context ('macOS Calendar.app / Linux default'). An agent can distinguish this from event/reminder siblings like list_events and list_reminders without opening any schema.

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

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

Explicitly tells the agent why to call it: to obtain calendar names for use with add_to_calendar. That is clear usage context, though it states no exclusions or when-not-to-use condition.

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

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

Annotations already establish the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower, yet the description goes well beyond: it documents pagination, the emoji marker legend for message state, and the newsletter/automated classification derived from RFC headers including the unsubscribe URI. This is behavior an agent could not infer from annotations or schema.

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

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

Front-loads the core purpose, then the output markers, then the alternatives and the ProtonMail caveat — a sensible ordering with no filler sentences. The dense emoji legend is information-carrying but slightly heavy for a description that must also stay scannable.

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

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

With 13 parameters, all schema-documented, plus an output schema, the description does the right thing by not re-explaining returns. It covers pagination, filtering, sibling routing, and the ProtonMail label quirk. The only residual is that the relationship to get_emails/search_emails is left unstated.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns above baseline by adding a non-obvious convention the schema lacks: ProtonMail labels are IMAP folders reached via mailbox="Labels/X", which meaningfully extends how the mailbox parameter should be used.

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

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

States a specific verb and resource ('List emails in a mailbox') plus its scope ('with optional filters'), and explicitly routes full-body retrieval to get_email. It does not, however, differentiate itself from the confusingly similar siblings get_emails and search_emails, which an agent must disambiguate.

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

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

Gives concrete usage instructions: call get_email for full bodies, and for ProtonMail run list_labels first then list_emails with mailbox="Labels/X". That is real when/how guidance. It stops short of saying when to prefer this over search_emails or get_emails, so no explicit exclusion is offered.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that by enumerating the returned fields (id, title, start/end, location, calendar name), which matters since there is no output schema. It does not disclose ordering or pagination behavior.

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

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

Purpose and filters are front-loaded, then usage guidance, then return shape — a sensible order with no filler. Slightly verbose in listing return fields, but each sentence carries distinct information.

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

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

Covers purpose, filters, usage triggers, and return values, and the annotations cover safety, so an agent has what it needs to call this correctly. Minor gaps remain around result ordering and whether the limit truncates silently, but with a fully described schema and no output schema this is close to complete.

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

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

Schema description coverage is 100%, so every parameter including defaults, ISO format, and the limit bounds is already documented in the schema. The description restates the filter axes (title, date range, calendar name) without adding syntax or semantics beyond them, and never mentions the row limit. Baseline 3 applies.

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

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

States a specific verb and resource ('List local calendar events') plus the filter dimensions available, which distinguishes it from siblings like list_calendars (enumerates calendars) and extract_calendar (parses events out of email). An agent can pick this tool without opening the schema.

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

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

Gives two concrete when-to-use triggers: checking for existing events before creating one, and verifying a recently added event. It stops short of naming alternatives or exclusions (e.g., when to prefer extract_calendar or add_to_calendar), so it is clear context without full routing.

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

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

Beyond the readOnlyHint annotation it discloses real behavior: automatic detection of the label backend (ProtonMail folder-labels, Gmail X-GM-LABELS, IMAP keywords) and the ProtonMail folder-label representation. It omits pagination and return shape, but adds meaningful context that annotations do not cover.

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

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

Four short sentences, front-loaded with the core action, then backend behavior, then the ProtonMail caveat and the routing hint. No filler sentences.

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

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

For a read-only single-param list tool with no output schema, the description covers purpose, backend variance, and the ProtonMail edge case that would otherwise trip an agent. It stops short of describing what the returned entries look like, the only notable gap.

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

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

Schema coverage is 100% with a single 'account' parameter already described as coming from list_accounts; the description only alludes to 'an email account' and adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

Specific verb+resource ('List available labels for an email account') with the scope narrowed by naming the three label systems it handles. It also distinguishes itself from folder-oriented siblings by noting that ProtonMail labels surface as IMAP folders under Labels/.

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

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

Gives concrete follow-up usage: pair the result with list_emails and mailbox="Labels/<name>", which is exactly the workflow an agent needs. It does not explicitly say when to prefer list_mailboxes or list_labels, so no full when-not guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful output context (unread counts, special-use flags), but says nothing about ordering, pagination, or what happens for accounts with no mailboxes.

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

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

Two short sentences with zero filler; the capability statement leads and the prerequisite follows. Every clause earns its place.

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

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

With an output schema present, return-value detail is handled elsewhere, and annotations cover the read-only nature. The prerequisite to call list_accounts closes the main gap; only edge cases like empty accounts or result ordering are unaddressed.

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

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

Schema description coverage is 100% for the single 'account' parameter, so the schema already documents it. The description only reinforces provenance ('from list_accounts'), adding little beyond the schema's own wording.

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

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

Specific verb+resource (list mailbox folders) scoped to a single account, and it names what the result carries: unread counts and special-use flags. That distinguishes it from sibling listers like list_accounts and list_labels, though it does not explicitly contrast itself with create_mailbox/rename_mailbox beyond the obvious naming.

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

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

It gives an explicit prerequisite ordering: 'Use list_accounts first to get the account name,' which tells the agent the required call sequence. It stops short of stating when-not to use it or naming alternative folder-inspection tools such as find_email_folder.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the shape of the returned items (descriptions and suggested labels), which is modestly useful, but says nothing about ordering, filtering, or whether presets are built-in versus user-created.

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

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

A single front-loaded sentence with no filler or repetition. Every clause (what is listed, and what each item includes) earns its place.

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

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

With no input parameters, no output schema, and annotations covering safety, the definition is nearly sufficient as-is. It partially compensates for the missing output schema by naming the returned fields, though the list's scope and ordering remain unspecified.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-argument tool applies.

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

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

States a specific verb and resource (list presets) and goes further by naming what each entry contains: descriptions and suggested labels. It is clearly distinguishable from the email/calendar siblings, though it never explicitly contrasts itself with adjacent tools like list_templates or list_labels.

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

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

There is no guidance on when an agent should call this versus list_templates or list_labels, nor what an 'AI triage preset' is used for downstream. Usage must be inferred entirely from the tool name.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavior beyond them: the default that only incomplete reminders are returned, and an enumeration of returned fields, which matters since no output schema exists.

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

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

Four short sentences with no filler, front-loading the source, filters, and the default-completion behavior before use cases. The return-field sentence is slightly list-like but earns its place given the absence of an output schema.

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

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

With no output schema, the description usefully enumerates returned fields (id, title, due date, completion status, priority, list name), and covers default filtering and search modes. It is complete for correct invocation, with only pagination behavior (beyond the limit param) left to the schema.

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

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

Schema description coverage is 100%, so the schema already documents limit, title, list_name, and include_completed including defaults and bounds. The description only restates filter capability ('Search by title or list name') and the incomplete-by-default behavior, adding little syntax or format detail. Baseline 3 applies.

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