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

Annotations already declare it is a write (readOnlyHint=false), not idempotent, non-destructive, and open-world. The description adds real behavioral context beyond that: the default target is the signed-in mailbox's own address book, and choosing a shared mailbox makes the contact visible to everyone with access, including via CardDAV. It stops short of covering permission requirements or what happens if a duplicate is still created.

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

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

Two sentences, both front-loaded with the action and the constraint; no filler, no repetition of the title. The scoping detail about shared-mailbox visibility is placed exactly where the account decision is made.

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 an 11-parameter, zero-required mutation tool with no output schema, the description covers the destination and the dedupe prerequisite well. Minor gaps remain: it does not state the minimum viable contact (all fields optional — can an empty contact be created?), nor what the tool returns or whether duplicates are rejected server-side.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the account default/shared semantics that the schema's 'account' description already covers in more detail, and adds no new field-level information (requiredness, email format, or address_book behavior) 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?

States a specific verb and resource ('Creates a contact in an address book') and immediately scopes the default destination, which distinguishes it from the read-only sibling mail_search_contacts. An agent can tell what this tool does and what it does not do 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 names the alternative ('Check mail_search_contacts first so you do not create a duplicate') and gives the selection rule for the account parameter (empty for the signed-in mailbox, shared mailbox name otherwise). Both the duplicate-avoidance workflow and the destination choice are 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?

Annotations already carry the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds genuine context the annotations don't: the write is non-communicating (draft is not sent) and the message remains user-reviewable. It stops short of noting that repeated calls create duplicate drafts (idempotentHint=false) or where the resulting draft id comes from for mail_send_draft.

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

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

Three sentences, zero waste, and the most important fact (does not send) is front-loaded right after the name. The alternative-tool pointer is placed directly after the workflow 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 12-param, zero-required mutation tool with no output schema, the description covers the essential semantics: it is a non-sending write, parameters mirror mail_send_email, and there are two follow-up paths. The one real gap is that it never says what comes back (a draft id) which mail_send_draft would need, but overall it is sufficient to call correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters in detail. The description only adds a cross-reference ('same parameters as mail_send_email') and highlights in_reply_to_id and attachments, which is helpful orientation but not new parameter-level meaning. Baseline 3 applies.

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

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

States a specific verb+resource combination ('Saves a message as a draft in the Drafts folder') and immediately scopes it against the send path ('does not send'). An agent can distinguish this from mail_send_email and mail_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?

Explicitly names the workflow (user reviews in webmail/phone and sends it themselves) and the alternative tool by name ('mail_send_draft sends it by id'), giving the condition that selects each path. Nothing is 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 destructiveHint=true and idempotentHint=true. The description adds useful behavioral context beyond annotations by stating the deletion is permanent and limited to drafts, preventing accidental attempts on non-draft messages.

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

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

Two short sentences, front-loaded with the action and scope. Every sentence earns its place with no redundant or filler content.

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

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

For a simple destructive delete-by-id tool, the description is complete: it states the action, permanence, and draft-only restriction. Annotations cover safety traits, the schema covers parameters, and no output schema is needed.

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

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

Schema description coverage is 100%, so both the 'id' and 'account' parameters are fully documented in the schema. The description only says 'by id' and adds no meaning beyond what the schema already provides.

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

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

States a specific verb and resource: 'Permanently deletes a draft by id.' It also scopes the operation by noting it works only on messages flagged as drafts, which distinguishes it from operations on sent or received mail.

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

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

Provides a clear context and a when-not condition: 'Works only on messages flagged as drafts — it never deletes sent or received mail.' However, it does not explicitly name alternative tools or spell out when to delete versus send or edit a draft.

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

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

Annotations only give a coarse profile (readOnlyHint=false because it writes to disk, destructiveHint=false, idempotentHint=true). The description adds substantive behavior: OCR is applied to scans/photos, OCR pages are marked '(OCR)' with a caution about their numbers, other types return only a saved path, and the source message is not modified.

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 return format, then the OCR caveat, then selection guidance — a logical order. Sentences are dense with parentheticals but each carries actionable content; slightly longer than strictly necessary.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly (text/PDF/image/OCR/other types). Combined with 100% schema coverage and annotations covering the safety profile, 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the 'attachment' parameter can be a partial name or a 1-based number, and OCR marking/preview behavior is tied to how results should be interpreted. It does not restate the page/save_dir/account parameters, which the schema already documents well.

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 with clear scope: downloads an attachment of a received message, saves it to disk, and returns its content. It also specifies the per-type return behavior (text/PDF/image), which lets an agent distinguish it from mail_get_email at a glance.

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?

Tells the agent how to select the attachment (by name or number from mail_get_email, unnecessary for single-attachment messages) and routes to mail_get_email as the source of the list. It also advises asking for a preview when a figure matters. It stops short of stating explicit when-not-to-use conditions (e.g. attachments that cannot be retrieved).

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 cover readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds genuinely useful behavior: HTML is silently converted to text unless html=true, and the call 'changes nothing (does not mark the message as read)'—a non-obvious behavior in mail clients. It omits any mention of size limits or permission requirements for shared mailboxes, which keeps it from a 5.

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

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

Three sentences, front-loaded with the core purpose and return payload, then alternatives, then the side-effect constraint. No filler and nothing repeated from structured fields.

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 properly compensates by naming the returned fields (headers, text body, attachment list) and the HTML conversion behavior. Coverage is strong, though an agent still lacks any note on size limits or how attachments must be fetched separately in bulk.

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

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

Schema description coverage is 100%, so all three parameters (id, html, account) are already documented in the schema; the baseline is 3. The description only adds provenance for the required id (comes from mail_search_emails) and implies the html behavior, without new meaning for the account parameter.

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 ('Returns a whole message by id') and enumerates exactly what comes back: headers, converted body text, and the attachment list. It also distinguishes itself from mail_get_attachment and mail_send_email, so an agent can place it among its siblings without opening a schema.

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

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

Explicitly says where the id comes from ('from mail_search_emails'), routes attachment reading to mail_get_attachment, and directs replies to mail_send_email with in_reply_to_id. Both the when-to-use and the alternative-routing conditions are stated outright.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. 'Changes nothing' largely restates readOnlyHint, and the description adds little beyond annotations apart from noting unread counts are included in the response. With annotations carrying the main burden, 3 is appropriate.

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

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

Two compact sentences with no filler; the discovery guidance ('call it first') is front-loaded and the read-only reassurance closes it efficiently.

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

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

Despite no output schema, the description enumerates what is returned (accounts, folders with unread counts, sendable addresses) and the zero-required-parameter discovery role. Nothing essential for calling 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 100% and the single optional 'account' parameter is fully documented in the schema, including a pointer back to this tool. The description adds no syntax or format detail beyond that, so the baseline 3 for high schema coverage applies.

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

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

States a specific verb (Returns) and three concrete resources (accounts, folders with unread counts, send-from addresses). This is clearly distinguishable from siblings like mail_search_emails or mail_get_email, which operate on messages rather than mailbox structure.

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

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

Explicitly tells the agent when to call it: 'Call it first when you do not know which folders or accounts exist.' This is a clear discovery-use condition. It doesn't name alternative siblings or state when NOT to use it, so it falls short of a 5.

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

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

Annotations already establish readOnly/idempotent/non-destructive/openWorld, so safety is covered. The description adds genuinely useful behavioral context: results merge address books with mail history, history is query-dependent, and an omitted query dumps the entire address book rather than failing. It stops short of describing result ordering or result caps.

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, then the two sources, then the usage trigger and default behavior. Three sentences with no filler, though the parenthetical about shared address books and the closing default-behavior sentence could be compressed slightly.

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

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

For a read-only lookup with no output schema and fully documented parameters, the description covers what the tool searches, when to reach for it, and the no-query fallback. Missing only result shape/ordering details, which are minor here.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including that include_history requires a query. The description reinforces the query-optional semantics but adds no syntax or value-format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Finds an e-mail address or phone number') and names the two data sources it spans: address books (own and shared) plus mail history. This clearly separates it from siblings like mail_search_emails (message content) and mail_add_contact (mutation).

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

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

Gives a clear when-to-use trigger ('whenever you need a person's or company's address before sending anything') and explains the no-query behavior. It does not explicitly contrast with mail_search_emails for the ambiguous case of looking someone up by message content, but the context is otherwise unambiguous.

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 readOnly/idempotent/non-destructive/openWorld, so the description's job is to add beyond that — and it does: default scope includes trash, results are newest-first, paging is via limit/offset, and the returned fields (ids, thread, sender, date, preview) are named. It doesn't discuss rate limits or result caps beyond the schema's limit=100.

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

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

Three front-loaded sentences with no filler: capability, return shape plus ordering/paging, then the default-scope caveat and its remedy. Every sentence earns its place.

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

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

With no output schema, the description must carry return-value information, and it does (ids for mail_get_email, thread, sender, date, preview, newest-first ordering). For a 13-parameter, all-optional search tool, an agent has everything needed to form a correct first call.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema carries the per-parameter meaning. The description adds cross-parameter guidance not present in the schema: the no-filter default, the inbox+unread combination for new mail, and thread_id suppressing other 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?

States a specific verb and resource (searches mail) and enumerates the searchable facets plus the thread-listing mode, which is a distinct capability. It references sibling mail_get_email as the natural follow-up, so an agent can place it in the workflow without opening another schema.

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

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

Gives a concrete conditional: with no filter it returns the latest messages from all folders including trash, and it directs 'what is new' queries to mailbox="inbox", unread=true. It also notes thread_id overrides other filters. It stops short of naming a competing tool to prefer for other cases, but the context provided is operationally clear.

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

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

Annotations already disclose readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds that the send is immediate, which is useful behavioral context beyond the annotations, though it does not discuss irreversibility, auth requirements, or after-send effects.

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

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

Two tight sentences with zero waste. The core action and the explicit-instruction constraint are front-loaded and easy to scan.

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

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

Given 100% schema coverage, rich annotations, and no output schema, the description supplies the essential context: what it sends, by id, with source and an immediate-send warning. Minor omissions such as explicit differentiation from mail_send_email and any after-send behavior keep it from being fully comprehensive.

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

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

Schema description coverage is 100%, so both optional parameters (from and account) and the required id are fully documented in the schema. The description adds only that the id comes from mail_create_draft or a drafts-folder search, which is helpful but does not meaningfully extend the other parameters.

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

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

States a specific verb (Sends) and resource (an existing draft) scoped by id. It distinguishes drafting from the sibling mail_send_email by operating on an existing draft, and it names mail_create_draft as a source of the id.

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

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

Gives a clear condition for use: only on the user's explicit instruction. It also specifies that the draft id comes from mail_create_draft or a drafts-folder search. It does not explicitly compare this tool against mail_send_email or state when not to use it.

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

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

Annotations already declare readOnly=false, openWorld=true, idempotent=false, so safety is partly covered; the description still adds high-value behavior: it sends IMMEDIATELY, cannot be undone, and leaves a copy in Sent. It does not cover failure behavior or how the send is confirmed, which keeps it short of a 5.

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

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

Three sentences, front-loaded with the core action and the irreversibility warning before the routing rules. Every clause carries actionable information; nothing is redundant with the title.

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

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

For a 12-parameter, zero-required, no-output-schema tool, the description covers the essentials an agent needs: immediacy, irreversibility, Sent archival, and which sibling to use instead. It leaves only minor gaps such as post-send confirmation or partial-failure behavior.

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

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

Schema description coverage is 100%, so the schema already documents recipient formats, account selection, attachment paths, and the in_reply_to_id thread behavior. The description only nods at in_reply_to_id in passing, adding essentially no semantics beyond the schema. Baseline 3 applies.

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

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

The first sentence gives a precise verb+resource ('Sends an e-mail from the mailbox') and immediately disambiguates the reply case via 'in_reply_to_id'. Combined with the named siblings (mail_create_draft, mail_send_draft), an agent can tell this apart from the drafting tools without opening a schema.

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

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

It gives explicit when-to-use ('only when the user explicitly said the message should go out'), an explicit when-not with the alternative ('otherwise create a draft (mail_create_draft)'), and a prerequisite ('never guess an unknown address, look it up with mail_search_contacts'). This is textbook routing guidance.

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