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

Goes well beyond the annotations: it explains the UID COPY mechanism, that nothing is moved or otherwise altered, the idempotent no-op when the label already exists, per-folder UID scoping, and partial-failure batch semantics with pre-mutation validation. This is a mutation tool whose side effects are fully disclosed.

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 is front-loaded and the bulleted rejection cases are scannable, but the entry is long and the case-variant label rule plus the repeated return-value explanation push it past what is strictly necessary. Every sentence is informative, though some could be tightened.

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 three-parameter mutation tool with a batch mode, the description covers preconditions, error taxonomy, side effects, and return shape. Even though an output schema exists, the explanation of the ok/failed batch result is a useful complement rather than a gap-filler.

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

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

With only 33% schema coverage, the description carries the load: it defines uid as a per-mailbox identifier accepting up to 100 values, tells the agent to take mailbox from list_emails/search_emails/get_email output, and clarifies that label may be given with or without the 'Labels/' prefix. It adds real meaning beyond the bare schema.

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

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

States a specific verb and resource ('Lägg till en etikett (Labels/…) på ett mejl') and immediately bounds the effect ('Mejlet ligger kvar i sin mapp'). It also implicitly distinguishes itself from move_email and flag_email by naming them as the correct tools for folders and Starred.

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

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

Explicit routing rules: use flag_email for Starred, move_email for Folders/…, create_folder to create a missing label, and list_mailboxes to discover existing ones. It also states when the tool is rejected, which is exactly the when-not guidance an agent needs.

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

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

Goes well beyond the readOnly/idempotent annotations: BODY.PEEK means nothing is marked read, the per-mailbox watermark is persisted server-side, watcher vs direct IMAP source is disclosed, UIDVALIDITY resync is handled and surfaced in note, and there is an explicit prompt-injection warning about untrusted message content. Raises conditions (invalid mailbox/UID, Bridge rejection) are also documented.

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 the core behavior and scoped paragraphs for watching, resync, and safety. Some redundancy exists because mailbox/since_uid are explained in prose and again under Args, and Returns restates field details, but with no output schema that restatement earns its place.

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

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

Given no output schema and 0% schema coverage, the description supplies the full response shape (messages fields, count, since_uid, last_uid, has_more, watching, last_event, source, note) plus the has_more>50 pagination hint and error cases. 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 description coverage is 0% and no enums exist, so the description carries the full load — and it does: mailbox defaults to INBOX (from PROTONMAIL_WATCH_MAILBOXES), and since_uid is defined as a UID threshold that must come from the same mailbox and explicitly does NOT advance the watermark.

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 opening sentence gives a specific verb (visa) plus resource (mejl) plus scope (sedan förra anropet / since_uid), which is an incremental "what's new" operation clearly distinct from the static listing done by list_emails. 'Väntar inte' further separates it from the blocking wait_for_new_email without ambiguity.

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

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

It states clearly when the watermark-based default applies versus when to pass since_uid (one-off query that does not advance the watermark), and the first-call-per-mailbox behavior is spelled out. It stops short of naming list_emails or wait_for_new_email as explicit alternatives, so the routing guidance is strong but 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 cover only the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description goes well beyond that: it discloses that nothing is sent, that validation/encoding/Message-ID/sender behavior is identical to send_email, that a bridge is required, that bcc persists visibly in the draft, and what happens on failure (ValueError, nothing saved; null uid with a 'note'). That is unusually rich behavioral context.

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

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

Front-loaded with the one-line purpose, then structured into narrative, Args, Returns and Raises sections that are easy to scan. Each block earns its place given the 0% schema coverage and absent output schema, though the prose between the purpose line and the Args list is somewhat long and could be tightened.

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?

A seven-parameter write tool with no schema descriptions and no output schema gets everything it needs: documented arguments, an explicit return shape ({uid, mailbox, message_id}) including the null-uid fallback, and declared error conditions. Nothing required 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 description coverage is 0%, so the description carries the full burden and does document all seven parameters, including which are optional (body_html, cc, bcc, reply_to) and that to/cc/bcc accept a string or a list. The per-parameter glosses are terse ('Ämnesrad', 'Brödtext i klartext') rather than adding format or constraint detail beyond type and optionality, so it compensates adequately but not exhaustively.

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 ('Skapa ett utkast i Drafts i stället för att skicka') and pins down the scope with 'Ingenting skickas'. It explicitly distinguishes itself from send_email (the pattern it mirrors) and points to send_draft and update_draft as downstream siblings, so an agent can tell it apart from every other write tool in the list.

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 the core when-to-use condition ('i stället för att skicka'), the intended review-then-send workflow ('skicka härifrån med send_draft när det är godkänt'), and routes listing of existing drafts to list_emails(mailbox="Drafts"). Alternatives and the condition that selects them are named rather than 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?

Annotations already declare readOnlyHint=false, destructiveHint=false and non-idempotence, so the safety profile is covered. The description adds real behavioral context beyond that: unprefixed names are rejected rather than auto-corrected, subfolder creation fails unless the parent exists, and names must be unique across folders and labels together with a descriptive error returned on collision.

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 action, then uses compact bullets for the prefix rules and a short Args/Returns block. The Returns section partially duplicates the existing output schema, which is minor waste, but nearly every line earns its place given the 0% schema coverage.

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 dual-mode creation tool with no schema documentation, the description supplies the prefix grammar, nesting rules, uniqueness constraint, and failure behavior, which is everything required to invoke it correctly. Return values are already covered by the output schema, so the brief Returns note is extra rather than 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 0% for the single 'name' parameter, so the description must carry the full load and does: it specifies the mandatory prefix syntax, gives concrete examples ('Folders/Projekt', 'Labels/Kvitton'), and explains nested-path behavior for each prefix. Nothing needed to build a valid argument is missing.

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 ('Skapa en ny mapp eller etikett') and immediately disambiguates the dual mode via the required Folders/ vs Labels/ prefix. This lets an agent distinguish it from siblings like add_label (label an existing email), rename_folder and delete_folder 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 explains when to choose each mode: an email lives in exactly one folder, but can carry multiple labels; subfolders are allowed while sublabels are not. It gives strong in-tool routing context but never names or contrasts sibling tools (add_label, rename_folder), so there is no explicit when-not-to-use.

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

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

Annotations already declare a non-destructive, non-idempotent write, so the safety baseline is covered. The description adds real behavioral context beyond that: nothing is dispatched, the draft lands in Drafts, the message is built exactly like forward_email with the original inline and all attachments/embedded images preserved, and it documents the ValueError conditions.

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 detail, then structured Args/Returns/Raises sections with no filler. Slightly longer than strictly necessary, but every section (build behavior, return shape, error cases) earns its place for a mutation tool.

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, but the description documents the return dict ({uid, mailbox: Drafts, message_id}) and the ValueError cases, and all six params are covered. For a non-idempotent mutation tool the definition is largely complete, with only minor gaps such as recipient format expectations.

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

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

Schema coverage is 0%, so the description must carry the parameter burden, and it does – all six parameters are described in the Args block. The mailbox entry adds genuine meaning not present in the schema ('Mappen som UID:t kom från… UID:n gäller per mapp'), explaining why the mailbox must accompany the UID.

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 precise verb+resource ('Skapa en vidarebefordran som utkast' – create a forward as a draft) and immediately distinguishes it from the sending tool forward_email ('i stället för att skicka den'). An agent can tell this apart from forward_email, create_draft, and send_draft 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?

Clearly frames the use case ('i stället för att skicka den') and names the follow-up action ('granska i Proton eller skicka med send_draft'), routing the agent to the alternative send path. It does not spell out explicit when-not conditions or contrast against create_draft/create_reply_draft, so it falls just short of a full 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 only cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false) and do not explain behavior. The description adds substantial context: nothing is sent, the draft lands in the Drafts mailbox, threading is achieved via In-Reply-To/References, recipients are derived from Reply-To/From, and ValueError is raised for missing originals or refused saves.

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

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

Well front-loaded: the draft-vs-send distinction leads, followed by construction details, args, returns, and raises. The reply-construction paragraph is dense but every sentence adds real information about threading and quoting, so little is wasted despite the length.

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, but the description documents the return shape ({uid, mailbox: Drafts, message_id}) and the error cases. Combined with complete parameter documentation, an agent has everything needed to call 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?

Schema coverage is 0% and there are 8 parameters, so the description must carry the full burden — which it does. It explains each parameter, including the non-obvious constraint that UID is per-mailbox and mailbox is mandatory, and that bcc is stored in the draft and quote_original defaults to True.

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 (create a reply draft) and immediately delimits it: it creates a draft rather than sending, and is built exactly like reply_to_email. An agent can distinguish it from create_draft, create_forward_draft, and reply_to_email 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 paths: review and send in Proton, or send from here via send_draft once approved. The sibling reply_to_email is named as the behavioral template. When-to-use and the follow-up action are both stated rather than 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?

Beyond destructiveHint=true, the description discloses irreversibility of permanent=True, mailbox-specific restrictions, 20–40s view lag, the up-to-45s retry wait, ambiguous-UID failure handling, and the exact batch contract (per-UID ok/failed, one IMAP command, whole call rejected on invalid input). This is far richer than what the annotations convey and does not contradict them.

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

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

Front-loaded with the primary behavior and organized under clear headings (Standard, permanent=True, Args, Returns), so it is navigable despite its length. It loses a point for repetition, restating the already-in-Trash scenario three separate times and reproducing return-value detail that duplicates the existing 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?

For a destructive, batch-capable IMAP tool with two modes, every decision-relevant fact is present: preconditions per mailbox, irreversibility, timing expectations, ambiguity handling, and per-UID batch results. Nothing an agent needs 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?

With schema description coverage at only 33% (mailbox and permanent have no schema description), the Args section compensates fully: it explains that UIDs are per-mailbox, that mailbox is required and should come from the mailbox field of list_emails/search_emails/get_email, and that uid accepts one string or up to 100 UIDs from the same mailbox.

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 first sentence states a specific verb+resource+mechanism: 'Ta bort ett e-post genom att flytta det till papperskorgen (Trash)', and it clearly separates the two operating modes (default move vs. permanent=True). It does not, however, name or contrast itself against the sibling move_email, which is the nearest alternative an agent might confuse it with.

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

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

The description gives explicit when-to-use and when-NOT-to-use rules: works from INBOX, Archive, Sent, Spam, Drafts, Folders/…; rejected for All Mail, Labels/…, Starred, and for mail already in Trash, with the reason (Bridge would permanently delete) and the corrective action ('ange mappen där mejlet ligger i stället'). Alternative routing is spelled out rather than inferred.

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

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

Beyond the destructive annotation, it explains exactly what happens: emails are not deleted, labels are removed from all emails, folder emails remain in All Mail, and Proton's handling of subfolders is unknown. This is highly valuable behavioral context for a destructive operation.

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

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

The description is detailed but well organized: purpose first, then constraints and effects, followed by Args and Returns. It is slightly longer than strictly necessary, but almost every sentence adds relevant operational detail.

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

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

Given the destructive nature, unknown subfolder behavior, and two parameters, the description provides all essential context for correct invocation. An output schema exists, and the description still clarifies the return/error contract usefully.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It fully explains name with required prefixes and examples, and explains force including its default and effect.

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-resource pair: deleting a folder or label, with explicit prefix formats (Folders/… and Labels/…). This clearly distinguishes it from siblings such as create_folder, rename_folder, and delete_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?

It gives clear conditions: the folder must be empty and have no subfolders, system folders cannot be deleted, and force=True overrides the empty-folder restriction. It does not explicitly compare against sibling alternatives, but the allowed and disallowed cases are well defined.

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 substantial context beyond the annotations: it confirms the already-starred no-op, documents partial-success batch semantics with per-UID ok/failed results, and specifies that an invalid UID or more than 100 UIDs rejects the entire call before any change. These are exactly the failure modes an agent needs and none are derivable from idempotentHint/destructiveHint alone.

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 the key statement and organized into clear Args/Returns/error blocks, with every behavioral claim earning its place. The Returns section partly restates the batch response shape that an output schema already covers, which is mild redundancy but aids the invalid-UID rejection explanation.

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 an output schema present, the description covers the semantic meaning of the flag, the mandatory folder scoping, idempotency, partial-failure behavior and whole-call rejection cases. Nothing material is missing for correct invocation.

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

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

Schema coverage is only 50% (mailbox has no schema description), and the description fully compensates: it explains that mailbox is required, that UIDs are folder-scoped so the same number in another folder is a different message, and where to source the value. It also characterizes uid as either a single UID or a list of up to 100 from the same mailbox, beyond the anyOf structure.

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

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

States a specific verb and resource ('Stjärnmärk ett mejl') and immediately pins down the underlying mechanism (IMAP \Flagged = Proton Starred), so the agent knows exactly which state change occurs and which sibling (unflag_email) it is the inverse of. It also rules out side effects: the message is not moved and nothing else is altered.

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 operational guidance: mailbox is mandatory and must be taken from the mailbox field returned by list_emails, search_emails or get_email, because UIDs are scoped per folder. It does not explicitly contrast with unflag_email or state when not to use it, but the counterpart is unambiguous from the surrounding toolset.

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 the safety profile (destructiveHint=true, openWorldHint=true, idempotentHint=false), and the description adds real behavioral detail on top: the Fwd: prefix, inline original in both text and HTML, attachment carry-over rules, the 20-file / 25 MB limit and PROTONMAIL_ATTACHMENT_DIR constraint on extra attachments, the partial-recipient-refusal error and the advice not to resend to everyone, and the ValueError for an unknown UID. The one gap is that it never explains what makes this operation 'destructive' despite destructiveHint being true.

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 the one-line purpose, then cleanly separated Args / Returns / Raises sections, so an agent can scan it quickly. It is somewhat verbose — the HTML-vs-text narration and the Returns sentence ('True om mejlet skickades') partly restate what the output schema already provides — but nothing is genuinely wasted.

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 mutation tool with a 0%-covered schema, the description supplies everything needed to call it correctly: parameter meanings, the per-folder UID trap, attachment limits, error semantics (which recipients failed, whether anything was sent) and the success return. The output schema covers return values, so the description's brief Returns note is sufficient rather than 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 0%, so the description carries the full burden and does: uid, to, cc, bcc and body are all described, and mailbox — the highest-risk parameter — gets an explicit warning that UIDs are per-folder and must be taken from the mailbox field returned by list_emails/search_emails/get_email. The attachments parameter is also qualified (extra files beyond the original's, filename or list, max 20 / 25 MB), which the schema does not convey.

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 concrete verb+resource (forward an email) and enumerates exactly what is carried over: original text, HTML version, attachments, attached emails and embedded images, plus the Fwd: prefix and inline 'Forwarded message' block. It is not, however, differentiated from the sibling tools that also emit mail (send_email, reply_to_email, create_forward_draft, send_draft), so an agent gets no help picking among them from this field alone.

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: it is clearly the tool for passing on an existing message, and the mailbox argument points the caller at list_emails/search_emails/get_email as the source of that value. There is no explicit statement of when to prefer this over send_email or create_forward_draft/send_draft, and no when-not 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?

Goes well beyond the annotations: discloses BODY.PEEK (no read-marking), no mailbox mutation, directory permissions/ownership checks, no-overwrite rename behavior, macOS quarantine flag, untrusted-content handling, invisible-character sanitization, and full error conditions. The write-to-disk behavior behind readOnlyHint=false is fully explained.

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 is front-loaded and the save=True/save=False split is clearly sectioned, so it reads well. It is long, but the length is largely justified by the edge cases; a few details (e.g. exact dir naming) could be trimmed.

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 args, full return shape (including untrusted_content_notice and sanitized counters), message/rfc822 special case, and enumerated error conditions. For a file-writing tool with no output schema and no annotations on safety nuances, nothing an agent needs 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?

With 0% schema description coverage, the description carries the burden and does so: uid, mailbox (obligatory, UIDs are per-folder), index (0-based position in get_email's attachments), and save (default True) are all defined with meaning beyond the bare schema types.

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

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

States a specific verb and resource (fetch an attachment from an email) and immediately names its two operating modes (save vs. inline read). An agent can tell this apart from get_email, which lists attachments, 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?

Explicitly routes save=True vs. save=False, tells the agent to use save=True when a file exceeds PROTONMAIL_ATTACHMENT_MAX_INLINE_BYTES, and clarifies that index refers to the attachments list from get_email. The when-to-use conditions are all present.

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 readOnly/idempotent annotations: it discloses untrusted-content handling, invisible-character stripping per field, the '[U+XXXX]' display convention in addresses, exclusion of hidden HTML from body_plain, message-id normalization, and the response fields (untrusted_content_notice, sanitized, suspicious_content, hidden_html, date_iso). This is exactly the behavioral context annotations cannot carry.

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 the purpose, then organized into Args/Returns/Raises, and almost every sentence carries required information. It is dense and somewhat long, but the length is justified by the security and format details rather than 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?

No output schema exists, yet the description enumerates the returned fields, their meaning, date_iso behavior, and the ValueError conditions. Together with a read-only tool whose safety profile is already in annotations, nothing an agent needs to call or interpret 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?

With 0% schema description coverage the description must carry all parameter meaning, and it does: uid is per-mailbox, mailbox is mandatory and folder-scoped, body_format's three enum values are each explained with their body_plain/body_html behavior, and max_length's default, None semantics, and full-format bypass are stated explicitly.

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?

Starts with a specific verb and resource ('Hämta fullständigt innehåll för ett e-post via UID'), and 'fullständigt innehåll' implicitly separates it from the header-only sibling get_email_headers. An agent can identify the operation and its scope immediately.

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 procedural context: the required mailbox value should be taken from list_emails, search_emails, get_thread, or the draft tools, and it warns that a UID is only meaningful within its folder. It stops short of explicit when-to-use-vs-alternatives guidance (e.g. versus get_email_headers or get_thread).

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 annotations' readOnly/idempotent/non-destructive hints, it discloses BODY.PEEK usage, that the mail is not marked read, that values are raw (RFC 2047 not decoded), the untrusted-content handling, and the sanitization rules for invisible characters and message_id.

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 the one-line summary, then Args/Returns/Raises. It is dense and long, but essentially every sentence adds distinguishing or behavioral information; only minor tightening is possible.

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 fully documents the return dict (which header keys, that missing headers are absent rather than empty) plus untrusted_content_notice, sanitized and suspicious_content, and the ValueError conditions.

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

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

Schema coverage is 0%, so the description must carry the burden, and it does: uid is the mail's UID and mailbox is required, with the crucial note that UIDs are per-folder and where to source the mailbox value from list_emails/search_emails/get_thread.

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 with scope: fetch a mail's headers without the body, quickly, with nothing modified. It also explicitly distinguishes itself from get_email/list_emails/search_emails as the raw-values tool versus the readable-text 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?

Explicitly tells when to use this (analysis of raw values such as Message-ID or Reply-To) and names the alternatives that give decoded/readable output. The condition that selects each sibling is spelled out, not left to inference.

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 readOnly/idempotent/non-destructive, but the description adds real behavioral value: it throws on a nonexistent folder and on container folders (Folders/Labels, selectable:false), pre-empting a whole class of failed calls.

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 plus a short Args block; the core behavior and the error condition are front-loaded, with no filler beyond the compact argument note.

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-param read tool with strong annotations and no output schema, the description covers purpose, default, and failure modes adequately; only the exact return shape is left 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?

Schema description coverage is 0%, so the description must carry the load. It defines mailbox as a folder name, notes the INBOX default, and implicitly constrains valid values via the selectable:false distinction from list_mailboxes.

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 (Hämta) and the exact payload: count of messages and unread in a folder. This is distinguishable from list_emails/get_email_headers, which return content rather than aggregate counts.

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

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

Usage is implied (check mailbox stats) rather than stated. It references list_mailboxes to explain which folders are valid, but never says when to prefer this tool over e.g. list_emails or check_new_emails.

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 readOnly/idempotent/non-destructive, but the description adds substantial operational context: nothing is modified and no mail is marked read, searches take 3–8 s on a ~30k-message account, hard caps of ten searches / 200 Message-IDs / 60 s, and that other tools may run between searches. It also defines exactly when complete becomes False and why note explains it.

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

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

Purpose is front-loaded and every paragraph is load-bearing, including the prompt-injection warning about subject/display names and the '[U+XXXX]' address encoding. It is nonetheless dense, with security policy interleaved between mechanics and limits, which slightly dilutes scannability for a three-parameter tool.

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, so the description supplies the full return shape (mailbox, messages with uid/from/subject/date/message_id/flags, total, complete, note) as well as the ValueError conditions. Combined with the sibling routing and cap behavior, an agent has everything needed to call it and interpret partial results.

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

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

With 0% schema description coverage the description must carry the load, and it does: uid is scoped to mailbox, mailbox is the folder where the UID applies, and max_messages gains truncation semantics (start mail plus most recent when the thread is longer). The 1–200 range and default 50 largely duplicate what the schema already encodes, so this falls just short of full marks.

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 ('Hämta hela konversationen (tråden) som ett mejl ingår i') and immediately distinguishes itself from the sibling it could be confused with by noting the body is not fetched and that each message must be read with get_email(uid, mailbox=...). An agent can tell this apart from get_email and search_emails 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?

Explicitly routes the agent: use get_thread for the chain, then get_email per message with the mailbox field from the response. It also states the when-not conditions – messages replying without In-Reply-To/References are excluded, and a start mail lacking a Message-ID means no thread search is possible and only the start mail is returned.

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

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

Annotations only declare the safe-read profile (readOnly, idempotent, openWorld=false). The description goes far beyond that: it warns that subject/name are untrusted data, explains which fields get invisible characters stripped versus rendered as [U+XXXX], tells the agent not to reply to such addresses, and precisely defines when suspicious_content is set. This is exactly the extra behavioral context annotations cannot carry.

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 purpose, then safety, then Args and Returns in a scannable layout. The security paragraph is long but every clause conveys a distinct rule, so it earns its space.

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 supplies the return shape (mailbox, messages, total, page, pages, has_more) and the important note that a UID is only valid within its mailbox. Combined with documented params and safety rules, nothing needed to call this 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 0%, so the description must compensate, and it does: it documents all three parameters with defaults, the 1-based page semantics, the 1–100 page_size bound, and the edge case that one page past the end returns an empty list. Only minor format details (e.g. valid mailbox naming) are left implicit.

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 (list) and resource (emails) plus the scope (in a folder), with metadata and page-based pagination called out. An agent can tell it apart from get_email or list_mailboxes by the resource, but it never explicitly contrasts itself with search_emails, the closest sibling.

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 statement of when to use this tool versus alternatives such as search_emails or get_email_headers. Usage is only implicit from the verb. The security handling text is valuable but is not tool-selection 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: container entries cannot be opened and hold no mail, selectable=False identifies them, and label names escape "/" as "\/", which affects downstream calls.

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 the one-line purpose, then an organized per-field breakdown. It is slightly longer than a zero-parameter list tool strictly needs, and some of the field documentation overlaps the output schema, but every entry carries a semantic note rather than pure 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?

With an output schema present and annotations covering the safety profile, return values need not be explained, yet the description usefully documents the semantics an agent needs (type taxonomy, container handling, escaping). The only omission is any note on result size or whether this is the canonical way to enumerate mailboxes vs. get_mailbox_status.

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, which is the baseline-4 case. The description correctly spends no space on arguments and instead documents the returned fields.

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?

"Lista alla mappar/etiketter i brevlådan" states a specific verb (list) and resource (folders/labels in the mailbox), so the core purpose is unambiguous. It does not, however, explicitly distinguish itself from sibling tools such as get_mailbox_status or list_emails, leaving that differentiation to inference.

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 implicit usage guidance in the tip to pass the returned name unchanged to other tools, and the description is read-only enumeration so its role is fairly evident. But it never states when to call it versus alternatives (e.g. get_mailbox_status for counts/status) or any prerequisites, so usage 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?

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description goes well beyond them: it documents the throw-on-missing-UID behavior, Bridge denial handling, partial-success semantics with one result per UID in a single IMAP command, and that an invalid UID or >100 items rejects the whole call before any change. That is exactly the destructive/atomicity context 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?

Structured with clear Args/Returns sections and front-loaded verb; every sentence carries operational information. It is somewhat verbose and the Returns block duplicates information already present in the output schema, which costs a point.

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 mutation with two required params, the definition covers inputs, per-folder semantics, atomicity, partial-failure shape and error conditions — more than enough for an agent to call it correctly, even though the output schema already exists.

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

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

Schema coverage is only 50% — uid is described in the schema but mailbox is not. The description compensates by explaining the per-folder UID semantic (same number in a different mailbox is a different email) and where to source the mailbox value, adding meaning the schema lacks.

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 ('Markera ett eller flera e-post som lästa') and clarifies the single-vs-batch scope up to 100 UIDs. The read/unread distinction is clear from the verb, though it never names the sibling mark_email_unread, so it does not fully earn sibling differentiation.

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

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

Gives real context: mailbox is mandatory, UIDs are per-folder, and the value should come from the mailbox field returned by list_emails, search_emails or get_email — a concrete cross-reference to sibling tools. However, it offers no explicit when-to-use vs alternatives (e.g., flag_email) or exclusions, 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 already establish the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description goes well beyond them: it discloses error behavior when the UID is absent or Bridge denies, partial-failure batch semantics (ok/failed split within a single IMAP command), and atomic rejection when the UID is malformed or exceeds 100 entries. That is rich mutation-behavior context not available from 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?

The description is long but structured with Args/Returns sections and front-loads the core action before the semantics. Nearly every sentence earns its place (batch behavior, error cases, UID scoping), though the Returns detail is somewhat verbose given an output schema exists.

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

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

For a two-parameter mutation tool with annotations present and an output schema defined, the description covers everything needed to call it correctly: required per-folder UID scoping, batch limits, partial-failure handling, and failure conditions. Nothing material 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 only 50% (mailbox has no schema description), and the description compensates by explaining that UIDs are scoped per mailbox, that the same number in another folder is a different email, and by naming the sibling tools whose responses supply the mailbox value. It also reiterates the batch response shape for uid, adding real meaning beyond the schema.

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

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

The opening line names a specific verb and resource ('Markera ett eller flera e-post som olästa') and immediately conveys batch capability. An agent can distinguish this from mark_email_read, flag_email, and unflag_email 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?

The description tells the agent where to obtain the mailbox value (from list_emails, search_emails, get_email responses), which is workflow guidance. However, it never states when to prefer this tool over siblings such as mark_email_read or flag_email, and gives no exclusions or prerequisites for the operation itself.

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, idempotentHint=false and readOnlyHint=false, but the description adds substantial beyond-annotation context: the specific Bridge-side guards that reject a move, the 20-40s view lag, the idempotent Trash/Drafts no-op behavior, and the note field explanation. However, it does not describe authentication or rate-limit concerns, and much of the mutation-risk detail is partly implied by the destructive annotation.

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

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

The purpose and folder-vs-label routing are front-loaded, and the bulleted rejection list is well structured. The main cost is the lengthy 'Returns' section, which largely duplicates the existing output schema and the rest of the prose, so it is slightly longer than it needs to be.

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

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

For a destructive, multi-UID mutation tool with only 33% schema coverage, the description covers the source/mailbox requirement, the batch response shape, per-UID failure handling, guard conditions, and the Trash/Drafts special case. Combined with the output schema and annotations, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is only 33% (mailbox and target_mailbox are undocumented in the schema), so the description carries real weight: it defines mailbox as the source folder, stresses that UIDs are per-mailbox, and tells the agent to reuse the mailbox field from list_emails/search_emails/get_email responses. The uid semantics (string or list of up to 100 from the same source) are also clarified here.

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 ('Flytta ett e-post till en annan mapp') and immediately scopes it ('Bara det angivna mejlet påverkas'). It explicitly distinguishes its domain from siblings by naming add_label, remove_label, flag_email and unflag_email and explaining that labels behave differently from folders.

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

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

Gives explicit when-to-use routing: folders are handled here, labels are handled by add_label/remove_label, starring by flag_email/unflag_email. It also enumerates the exact conditions that are rejected (same source and target, All Mail, INBOX<->Sent, Starred, Trash/Drafts from a label) so the agent knows when NOT to call 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 declare destructiveHint=true and idempotentHint=true, and the description adds substantial context beyond them: the underlying UID EXPUNGE mechanics against the label's view, per-view UID scoping, and confirmation that the message is not deleted or moved to Trash. Batch semantics are disclosed precisely, including that invalid UIDs or more than 100 abort the whole call before any change, and that partial Bridge denials are re-verified and counted as ok.

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 the core action and the non-destructive guarantee, then mechanics, error cases, args and returns in a logical order. It is long, and the batch return shape is repeated verbatim in both the description and the uid schema field, which is mild redundancy; for a tool with this many failure modes the length is mostly justified.

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

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

Despite an output schema existing, the description still covers return shapes, partial-failure accounting and pre-flight validation, so an agent knows both the success and failure contract. Combined with annotations and the schema, nothing needed to invoke this 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 description coverage is only 33%, so the description carries the burden and does: mailbox is explained as per-folder UID scoping plus where to obtain the value (list_emails, search_emails, get_email), label is shown with and without the "Labels/" prefix, and uid batch behavior and the 100-item limit are stated. It adds semantics the schema does not encode.

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 opening sentence states a precise verb+resource+scope: remove a label from an email without otherwise touching the email, and immediately clarifies that the message is not deleted or moved to Trash. This distinguishes it cleanly from siblings such as delete_email, unflag_email and add_label. An agent can select it 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?

It names the alternatives and the conditions that route elsewhere: use unflag_email for Starred, use create_folder("Labels/Namn") to create a missing label, and use the label itself as mailbox when Message-ID lookup is ambiguous. It also enumerates the exact rejection conditions (label absent, label missing, system folder, UID not in mailbox, >100 UIDs), which is explicit when-not-to-expect-success 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 destructiveHint=true and idempotentHint=false, so the safety profile is covered structurally. The description adds real behavioral context beyond that: the same-prefix rule, the system-folder prohibition, and the error-on-failure contract ("annars kastas ett fel med förklaring").

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 operation, then constraints, then args and return value, with no filler sentences. Slightly padded by repeating the return value that an output schema already covers, but otherwise tight.

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 an output schema present, the description covers everything needed to call it correctly: scope, constraints, parameter formats, and failure behavior. It is close to complete, with only minor gaps around length limits and exact error conditions.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it does: it gives an example value for old_name ("Folders/Projekt") and new_name ("Folders/Projekt 2026") and states the prefix must match. It compensates well, only missing explicit notes on the 1–255 length bounds that the schema enforces.

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 (rename) and resource (folder or label), and the Folders/… vs Labels/… distinction separates it from siblings like create_folder and delete_folder. An agent can identify the operation 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?

Explicitly states when the tool does NOT apply: system folders (INBOX, Sent, Trash, All Mail) cannot be renamed, and a folder cannot become a label or vice versa. It gives clear context and exclusions, though it never names an alternative tool to use instead for those excluded cases.

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 write/destructive/openWorld, the description adds substantial context: Reply-To vs From resolution, the self-sent-mail heuristic (Proton-marked or present in Sent), automatic quoting format, attachment limits (20 files / 25 MB), the fact that original attachments are NOT carried over, and the refusal-on-rejected-recipient behavior with a warning not to resend to all.

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?

Structured with Args/Returns/Raises and front-loaded with the core behavior. Dense and mostly earning its place, though the paragraph on self-sent detection is lengthy for an edge case and could be tightened.

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 destructive mutation tool with 0% schema coverage, the description covers return value, the specific ValueError text and its cause, recipient-refusal behavior, and every argument. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 0%, so the description fully carries the burden — and it does: uid, body, the mandatory per-mailbox semantics of mailbox (same UID in another folder is a different message), body_html, reply_all's inclusion of To/Cc excluding your own account, cc/bcc, quote_original's default, and attachments' directory constraint and limits.

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 ('Svara på ett e-post') plus the automatic header behavior (In-Reply-To, References, Re:-prefix), which clearly separates it from send_email. It never names a sibling tool (e.g. create_reply_draft) to differentiate explicitly, so it stops short of a 5.

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 practical guidance — the mailbox argument must come from the 'mailbox' field returned by list_emails/search_emails/get_email — but no statement of when to reply directly versus creating a draft (create_reply_draft/send_draft) or when reply_all should be preferred. Usage is implied rather than contrasted with alternatives.

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

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

Annotations already mark this as read-only, idempotent, non-destructive, and closed-world, but the description adds substantial behavioral context beyond them: security warnings about treating subject and display names as data, invisible-character handling, suspicious_content triggers, no flag/move side effects, decoded-header matching, quoted-printable limitations, has_attachment MIME rules, and ValueError conditions.

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

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

The description is long, but the length is justified by 16 undocumented parameters, security caveats, return details, and error conditions. It is front-loaded with purpose and AND semantics, then progressively discloses matching behavior, parameters, returns, and raises.

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

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

For a complex 16-parameter search tool with no output schema and 0% schema description coverage, the description is complete: it covers filters, matching behavior, security risks, return dictionary keys, completeness signaling, and raised exceptions.

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

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

Schema description coverage is 0% with 16 parameters, so the description carries the full burden. Its Args section defines every parameter, including filter meaning, substring/case behavior, date formats, boolean None semantics, max_results range and ordering, and size/attachment filters.

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: 'Sök e-post med filter' (search email with filters), and adds the key AND semantics for multiple filters. It does not explicitly name sibling alternatives such as list_emails, so sibling differentiation is implied rather than stated.

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 through its filter-focused purpose and detailed parameter semantics, but it does not explicitly say when to choose search_emails over list_emails, get_email, or check_new_emails. It also provides no when-not guidance beyond limitations on search matching.

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 destructive/non-idempotent/open-world, but the description goes well beyond them: Bcc header stripping, Bridge placing the mail in Sent, the conditions that cause a refusal with nothing sent, who removes the draft (Bridge vs. this tool), and that a partial delivery still delivered to the accepted recipients.

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?

Long, but front-loaded with the core action and organized into behavior, refusal conditions, deletion semantics, Args, Returns and Raises. The Returns and Raises detail is load-bearing since there is no output schema; a few sentences (e.g. the Bridge internalid aside) are dense but still earn their 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 output schema, the description supplies the return shape (sent, message_id, recipients, draft_deleted, plus note/warning) and the failure modes (ValueError, SMTPPartialDeliveryError) with what each implies for retry. An agent has everything needed to call and interpret it safely.

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

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

With 0% schema description coverage the description must carry the parameter meaning, and it does: uid is explained as the Drafts UID sourced from create_draft or list_emails, and mailbox is explained as always "Drafts" for confirmation. Only the exact UID format is left implicit.

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 with its full lifecycle: sends a Drafts draft exactly as it stands and then removes it. This is clearly distinguishable from send_email (composes and sends), create_draft and update_draft (which it references for the address-rewrite path).

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

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

Explicitly says to use it only once the draft is reviewed and approved, names update_draft for fixing ambiguous addresses, and points to list_emails(mailbox="Drafts") for finding drafts. It also gives an exclusion: after a partial delivery, do not resend to everyone.

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?

This goes well past the annotations (readOnly=false, destructive=true, openWorld=true, idempotent=false). It discloses attachment sandboxing (only files inside PROTONMAIL_ATTACHMENT_DIR, symlinks rejected), hard limits (20 files / 25 MB), the all-or-nothing rejection behavior, and critically the partial-recipient-failure semantics with an explicit instruction not to resend to everyone. That is exactly the behavioral context an agent needs for a non-idempotent send.

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?

Docstring-style Args/Returns layout is front-loaded and every bullet carries information; nothing is padding. The opening line is a near-restatement of the tool name, which is the only minor 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 destructive, non-idempotent send tool with an output schema and zero schema-level parameter docs, the description supplies everything an agent needs: all parameter meanings, attachment constraints, and the failure/partial-delivery contract. Nothing material 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 0% and there are 8 parameters, so the description carries the entire burden. It documents every parameter meaningfully: to/cc/bcc/reply_to address semantics, subject, plaintext body vs optional HTML body, and attachment filename-or-list with directory and size constraints. The schema is unusable without this text.

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 ('Skicka ett e-post' = send an email), which is unambiguous. However, it never distinguishes itself from the closely related siblings reply_to_email, forward_email, or send_draft, so sibling differentiation is left to inference.

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 reply_to_email, forward_email, or send_draft — all of which also put mail on the wire. The only operational guidance given is about attachment paths and not re-sending after a partial failure, which is not 'when to use' guidance.

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

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

The description goes well beyond the annotations: it explains the direct IMAP flag removal versus the Bridge Starred view only refreshing every 20-40 seconds, that the mail stays in its folder and is never deleted, the partial-failure case where the star is removed but the mail may linger in Starred for up to a minute, and the exact rejection conditions (UID not in mailbox, Bridge denial). This is consistent with destructiveHint=false and idempotentHint=true while adding information the annotations cannot carry.

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 the action, then structured into behavior, Args and Returns sections, so it is easy to scan. It is on the long side and the uid list behavior is restated in both the Args block and the schema, a minor redundancy, but every paragraph carries operational detail.

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

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

For a two-parameter mutation tool with a sync-timing quirk, this covers everything an agent needs: preconditions, per-mailbox UID scoping, batch limits, partial-failure semantics and rejection behavior. It even restates return shapes despite an output schema existing, which is redundant but not harmful.

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 only 50% (mailbox has no schema description), and the description fully compensates: it states mailbox is obligatory and why UIDs are scoped per folder, where to obtain the mailbox value, that up to 100 UIDs from the same mailbox are accepted, and that an invalid UID or more than 100 rejects the whole call before any change. This adds genuine semantics beyond the schema's anyOf constraint.

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 opening sentence names a specific verb and resource ('Ta bort stjärnmärkningen från ett mejl') and immediately grounds it in the IMAP \Flagged flag, so the operation is unambiguous. It never explicitly names the inverse sibling flag_email, so the agent must infer the pairing from the name, but the action itself is precise.

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 real contextual guidance: UIDs are per-mailbox, the mailbox value should be taken from the response of list_emails, search_emails or get_email, and 'Är det inte stjärnmärkt händer inget' sets expectations for the no-op case. It stops short of explicitly stating when to choose this over flag_email or other label tools, so the alternative-selection guidance is implied 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 annotations (destructiveHint=true only signals a write): it explains that omitted fields become empty and must be re-sent, which headers/parts are preserved byte-for-byte, the save-then-Trash-move ordering, the recoverability of the old draft, the new UID assignment, and the partial-failure state where the new draft is already saved. This is unusually rich behavioral disclosure for a mutation 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?

Front-loaded with the one-line purpose, then clearly partitioned by ERSÄTTS / BEHÅLLS / Args / Returns / Raises. The length is largely justified by the tool's complexity, though some prose (e.g. the cid/embedded-image nuance) is denser than strictly required.

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 supplies the full return shape (new uid, replaced_uid, replaced_moved_to, kept_headers, kept_attachments) and the failure modes with the exact post-failure state. Combined with the annotations covering the safety profile, an agent has everything needed to call 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?

Schema description coverage is 0%, so the description carries the full load, and it does: the Args block documents all 9 parameters including uid/mailbox semantics ('anger för att bekräfta att UID:t kommer därifrån'), accepted string-or-list forms for addresses, and the re-specification contract for cc/bcc/body_html. No meaningful parameter is left ambiguous.

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 precise verb+resource ('Ersätt ett utkast i Drafts med en ny version') and immediately scopes the effect ('Ingenting skickas'), which cleanly separates it from send_draft, create_draft and create_reply_draft. The agent can identify the operation 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?

Explicitly limits applicability ('Bara utkast i Drafts kan uppdateras') and routes the agent to the correct discovery path ('hitta dem med list_emails(mailbox="Drafts") och läs dem med get_email'). It also states a negative rule — do NOT re-run update_draft if the Trash move failed — which is exactly the when-not guidance this dimension rewards.

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: messages are fetched with BODY.PEEK and never marked read, the shared connection is released while waiting so concurrent tools work, watched mailboxes use IDLE while others poll every 5 seconds, and the first poll only sets the watermark. It also warns that email content is untrusted and must not be followed as instructions, and documents ValueError/TimeoutError behaviour precisely.

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 one-line purpose, then layers behaviour, Args, Returns and Raises in a scannable structure. It is longer than average but nearly every sentence carries information an agent needs, with only mild redundancy in restating defaults.

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 compensates by describing the return payload (same fields as check_new_emails plus timed_out and waited_seconds) and the empty-messages case on timeout. Combined with error semantics and the IDLE-vs-polling detail, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 0%, so the description carries the load: mailbox is documented as the folder to watch (default INBOX) and timeout_seconds as the maximum wait in seconds, 1–300, default 60. It adds semantic meaning (what the folder represents, what waiting means) but repeats the range/default already encoded in the schema, so it stops short of a 5.

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 ('Vänta tills ett nytt mejl kommer till mappen') with the bounding constraint (timeout_seconds) up front. It also distinguishes itself from the sibling check_new_emails by explaining that both share the same watermark, so an agent can tell the blocking wait apart from the polling check.

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?

Explains the decisive condition for immediate return (mail already arrived since the last call by this tool or check_new_emails) versus actually waiting, and clarifies that other tools remain usable during the wait. It never explicitly states the when-not-to-use case (e.g. 'use check_new_emails if you do not want to block'), so it falls just short of a 5.

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