mcp4mail

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

Goes well beyond the annotations (which only say non-readonly, non-destructive, non-idempotent) by disclosing hard limits — plain text only, no attachments, 100 kB, 50 recipients — and the side effect that a reply draft gets a "Re:" subject when none is given. That is exactly the operational context an agent needs before writing.

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 send/no-send distinction, then constraints, then the optional threading parameter. No filler and nothing redundant with the schema field descriptions.

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?

Mutation tool with annotations and an output schema, so return values need no explanation; constraints, non-delivery semantics, and threading behavior are all covered. Nothing material is missing for a correct 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 baseline is 3; the description earns above that by explaining reply_to_message_id's threading behavior and subject mutation and by pointing to search_messages as the id source, both of which are absent from the schema 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 (save a message or reply into Drafts) and immediately scopes it against sending. An agent can distinguish this from send_message 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 is not sent: the person opens their mail client and sends it themselves" gives clear when-to-use context and implicitly steers the agent to send_message for actual delivery. It also names prerequisites for reply_to_message_id (an id from search_messages), but never explicitly names the sibling tool to use instead.

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 idempotentHint=true and destructiveHint=false, but the description adds the concrete behavior behind that hint: 'Asking for a folder that already exists succeeds and returns it.' That is genuinely useful context an agent cannot infer from the hint alone. It does not discuss permissions or error cases, so not a 5.

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

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

Three short sentences, each carrying distinct information (purpose, idempotency semantics, optional parent usage), with the core action stated first. No filler or restatement of the name.

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

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

Covers purpose, idempotency, and the one non-obvious parameter; an output schema exists so return values need not be explained. Missing only explicit guidance on discovering account_id or handling failure cases, which are minor given the schema descriptions and annotations.

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 by clarifying that 'parent' accepts a path or a name and should be sourced from list_folders. That resolves the ambiguity of whether the value is an ID, path, or display name.

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

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

States a specific verb and resource ('Create a folder in a mailbox') with the scoping detail that the folder lives in a mailbox, and the subfolder case is called out. It does not explicitly name sibling tools, but the resource is distinct enough from create_draft, move_message, and list_folders that an agent can route without opening the schema.

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

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

Gives a concrete condition for the optional parameter ('Give "parent" ... to create a subfolder') and points at list_folders as the source of valid parent values. It stops short of stating when not to use this tool (e.g. if a folder already exists, prefer list_folders) or other preconditions, so it falls just short of full routing guidance.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral facts: the URL is signed and expires in 5 minutes, the URL path caps at 10MB while the inline path caps at 5MB, and the response shape differs (metadata + URL vs content_base64). The size/expiry tradeoff is exactly the kind of context an agent needs before choosing a mode.

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 action, then the required inputs, then the mode tradeoff, then the safety note — good ordering with no filler sentences. The closing "Only reads mail; it never changes the mailbox" is largely redundant with readOnlyHint=true and destructiveHint=false, costing a small amount of efficiency.

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 a full output schema and annotations, the description covers the operational facts that matter: where ids come from, 0-based indexing, expiry, and size ceilings per mode. Minor gap: no mention of behavior for an out-of-range index or a message with no attachments, which an agent picking an index would want to know.

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

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

Schema coverage is 100% and already documents the 0-based index and inline flag, so the baseline is 3. The description earns above baseline by adding the size-limit asymmetry between the two modes (10MB URL vs 5MB inline), which is not present in any schema field.

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

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

States a specific verb and resource ("Get one attachment of a message") and immediately distinguishes the operation from get_message by naming where the message id comes from. The attachment_index requirement makes it unambiguous that this retrieves a single binary/metadata object rather than the message body.

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 conditional guidance for the key decision: default to the signed URL, pass inline:true "when you cannot open URLs on this server, for example in a sandbox with restricted network access." It also names the upstream tools (search_messages, get_message) for obtaining the id, though it never states when to prefer get_message over this tool 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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description still adds substantive context: the password is never returned, ai_permissions defines the AI's allowed write scope and that out-of-scope tools are refused, indexed_at has a 15-minute refresh window with newer mail unsearchable, and sync_errors is conditionally present. These are non-obvious behaviors an agent cannot get from the annotations.

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

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

Three tight sentences, front-loaded with the core action and the password caveat, then field semantics. Every clause carries information the agent would otherwise have to guess; nothing is redundant.

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

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

Output schema exists, so enumerating returned fields is unnecessary, and the description instead supplies the interpretive context (permission scope, index freshness, conditional sync_errors) that matters for correct use. Only a brief note on what 'connection details' comprises or error behavior on an invalid account_id is missing.

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

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

Schema coverage is 100% and the single parameter already documents its origin ('Id from list_mail_accounts'). The description adds no additional constraint or format detail for account_id, so the 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?

Specific verb + resource ('Show the connection details of one of your mail accounts') with a clear scope limitation (a single account, password excluded). The singular 'one of your mail accounts' implicitly separates it from list_mail_accounts, and the schema reinforces that by sourcing account_id from list_mail_accounts, but the description never names the sibling explicitly.

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

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

Usage is only implied: the agent can infer this is the per-account detail lookup versus the list sibling, but there is no explicit 'use X when...' statement or exclusion. The rest of the description is spent on output-field interpretation rather than 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely non-obvious behavior: HTML is converted to text rather than returned as markup, attachments are listed as metadata only, and bodies are capped at 20000 characters with a 'truncated' flag signaling more content. These are exactly the traits an agent cannot infer 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?

Four short sentences, each carrying distinct information (purpose, id provenance, body/attachment behavior, truncation). The core capability is front-loaded and nothing repeats.

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-parameter read tool with an output schema and full annotation coverage, the description covers everything an agent needs: how to obtain the id, what the body looks like, what is excluded (attachment content), and how to detect truncation.

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

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

Schema coverage is 100% and the sole parameter's schema description already says 'The message id from a search_messages row,' so the description's 'give it the id of a row from search_messages' is essentially a restatement. Baseline 3 applies since the schema does the work.

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?

Opens with a specific verb and resource ('Read one message: its headers and body') and immediately scopes what is and isn't returned. It clearly distinguishes itself from search_messages (which supplies the id) and get_attachment (which supplies attachment content).

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 the id must come from a search_messages row, giving the required upstream workflow, and explicitly routes attachment-content requests to get_attachment. An agent knows both when to call this and when to call a sibling instead.

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 read-only/idempotent, so the description doesn't need to repeat that; instead it discloses the meaningful behavior: four possible states, the owner-approval gate, the 24-hour expiry that results in nothing being sent. That is exactly the context an agent needs beyond the safety hints.

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

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

One tight sentence with the outcome enumerated in a parenthetical; front-loads the purpose before the state list. No filler, though the parenthetical is dense.

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 one required parameter, an output schema present, and annotations covering safety, the description completes the picture by explaining what each state means and the expiry rule. Only polling/terminal-state guidance is missing.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema as the outgoing_message_id from send_message. The description adds no extra detail about the identifier, so baseline 3 applies.

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

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

States a specific verb+resource ('whether an email prepared with send_message was sent') and ties it to the sibling that creates the item, so the agent can distinguish it from get_message or search_messages. It stops short of naming the alternative read-content tool explicitly.

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

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

Implies the tool is used after send_message to poll for approval/send outcome, but gives no explicit when-to-use versus siblings or guidance on polling cadence or when the status is final.

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, and closed-world, so the safety profile is fully covered. The description adds that counts are returned and explains the semantics of the output fields, but since a full output schema exists, much of that is restating structured data rather than new behavioral context. The special_use explanation (locale-independent Sent/Trash/Drafts/Junk/Archive identification) is the one genuinely additive point.

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

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

Three short sentences, front-loaded with the primary action, and every clause carries information. Light redundancy with the output schema keeps it from being maximally 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?

With annotations, a single fully documented parameter, and an output schema, the description supplies what remains: the scope (one mailbox), the returned counts, and how to interpret path/name/special_use. Nothing essential for a correct call 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?

Only one parameter, and the schema documents it at 100% coverage ('Id from list_mail_accounts'). The description adds nothing about account_id and instead describes output fields, so it neither compensates nor detracts. Baseline 3 for full schema coverage.

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

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

States a specific verb and resource (list the folders) plus the scope (one mailbox) and the payload (message and unread counts). It is clearly distinguishable from every sibling, none of which list folders, though it never says so explicitly.

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

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

There is no explicit when-to-use or when-not-to-use statement, but the clause '"path" is what the other tools take' implicitly tells the agent this is the discovery step that feeds move_message, create_folder, and similar tools. That hint is useful but left for the agent to infer.

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 read-only/idempotent safety, yet the description adds substantive behavior: ai_permissions gates which tools the AI may use against a mailbox, indexed_at refreshes every 15 minutes so newer mail is unsearchable, and sync_errors is conditional. These are non-obvious constraints an agent could not infer 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?

Three tight sentences, front-loaded with the action and followed by usage then field semantics. Minor waste: explaining indexed_at and sync_errors duplicates what the output schema already exposes.

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

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

For a zero-parameter, read-only listing tool with a full output schema, the description supplies everything an agent needs: what it returns, what the id is for, and the freshness/permission caveats that affect downstream calls.

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

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

Zero parameters, so the baseline is 4; the description instead explains the semantics of the returned id and fields, which is useful orientation. No gaps to compensate for on the input side.

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 and resource ("List the mail accounts you have connected") plus the product context (mcp4mail), which distinguishes it from the singular get_mail_account sibling. An agent immediately knows this is the enumeration entry point.

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

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

"Use an account's id with the other tools" tells the agent this is a prerequisite/discovery call before get_mail_account, list_folders, search_messages, etc. It stops short of naming an explicit alternative or exclusion case, but the sequencing guidance is clear.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description adds genuinely new behavioral facts: the message receives a new id so it must be re-searched, and on Gmail a move out of a label removes only that label while the message persists in All Mail and other labels. That is exactly the non-obvious consequence an agent needs before calling.

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

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

Four short sentences, front-loaded with the operation, then prerequisites, then the consequence, then the provider-specific caveat. Every sentence carries information an agent would otherwise get wrong.

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?

An output schema exists and annotations cover the safety profile, so the description only needs to cover invocation prerequisites and side effects—both of which it does, including the Gmail label nuance and the id-invalidation 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 coverage is 100%, so the baseline is 3, and the description adds provenance for message_id (a search_messages row) and the accepted forms of folder (path, name, or special-use like Archive). The folder semantics are largely echoed from the schema's own description, limiting the added value 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 ('Move one message to another folder of the same mailbox') and constrains scope to a single message, which distinguishes it from sibling mutation tools like trash_message or set_flags. 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 directs the agent to obtain the message id from search_messages and the destination from list_folders or a special-use name, tying usage to specific sibling tools. It stops short of stating when not to use this tool (e.g., use trash_message for deletion), so it is clear context rather than full when/when-not coverage.

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

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

Annotations already declare readOnly, idempotent, non-destructive and non-open-world, so the safety profile is covered. The description adds real behavioral context beyond that: matching ignores case and diacritics, every word in the query must match, and it enumerates the returned fields. It does not mention result ordering or performance characteristics, so it is not exhaustive.

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

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

Three sentences, front-loaded with purpose, then return shape, then matching behavior, then routing. Every sentence is useful, though the field enumeration partially duplicates the 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?

Purpose, matching semantics, return shape, and sibling routing are all present; with an output schema and full param coverage, nothing an agent needs 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 100%, so the baseline is 3; the description earns extra by adding matching semantics not stated in the schema — diacritic/case folding and the 'every word has to match' conjunction rule. It does not restate limit/account_id, which is fine since the schema documents them 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 ('Find people you have exchanged mail with') plus the resource (contacts) and the exact return fields, which cleanly separates it from search_messages. An agent can identify the tool without opening the schema.

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

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

Gives an explicit routing instruction: use this to turn "Marie" into an address before calling search_messages. That names the alternative tool and the condition that selects it, leaving little 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 readOnlyHint and idempotentHint, yet the description adds genuinely non-obvious behavior: the index lags the live mailbox by ~15 minutes, matching covers headers and attachment filenames but never bodies, results are newest-first, rows are capped and flagged with "truncated": true. These are operational traits the agent cannot infer from any structured field.

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

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

Front-loaded with purpose, then staleness caveat, then matching semantics, then return shape, then truncation guidance — a sensible order with no filler. It loses a point for restating the get_message hand-off twice ('To look inside a message, call get_message' and 'To read the text of one message, call get_message with the id').

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 summarizes the row shape and emphasizes that bodies are never returned, which is the decisive fact for an agent deciding whether it has enough to answer. With a 7-param, all-optional tool, the refusal rule and truncation handling close the remaining gaps.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the refusal condition when all of query/since/until/folder are omitted (the schema's required list is empty, so this constraint is invisible there), and the newest-first default ordering. It does not add format syntax for the individual params, which the schema already handles.

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 names the exact resource and scope: header-only search over a local index, with listing by date or folder as the alternative mode. Crucially it distinguishes itself from get_message, the sibling that reads bodies, so an agent can route correctly 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?

It states positively when to use it ('leave the query out to list mail by since, until or folder alone'), gives the exclusion ('a call with no query and no since, until or folder is refused'), and names the alternative twice ('to look inside a message, call get_message'). All routing decisions are explicit.

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

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

Annotations already flag destructiveHint=true and non-idempotent, but the description adds the behavior that matters most: nothing is sent until the mailbox owner clicks a link within 24 hours, after which the message expires. It also discloses content limits and queue caps, and the draft-merge rule ('fields you give replace the draft's'), none of which are in the annotations.

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

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

Front-loaded with the purpose and the approval caveat, and nearly every clause carries operational information (limits, ids, follow-up). It is a single dense paragraph with several semicolon-joined ideas, which is efficient but slightly harder to scan than a short bulleted structure would 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?

Covers the full lifecycle an agent needs: preparation, the owner-approval delay and its 24-hour expiry, content and volume limits, draft/reply id sourcing, and how to check delivery. Since an output schema exists, the description is not obliged to describe return values, and it correctly just names outgoing_message_id.

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

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

Schema coverage is 100%, so baseline is 3; the description goes beyond it by explaining the interaction between draft_message_id and the other fields (supplied fields override the draft) and by tying reply_to_message_id to ids from search_messages. It adds no guidance on to/cc/bcc formatting or the array-vs-string union, which the schema leaves 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 specific verb and resource ('Prepare an email to be sent from this mailbox') and immediately clarifies the critical distinction from a normal send: it is a two-phase approval flow, not an immediate send. This separates it cleanly from siblings like create_draft and from any naive expectation of 'send_message'.

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

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

Gives explicit routing: use reply_to_message_id (id from search_messages) to reply in-thread, or draft_message_id to send a previously saved draft, plus the instruction to poll get_outgoing_status with the returned outgoing_message_id. It also states hard usage constraints (plain text only, no attachments, 100 kB, 20 recipients, 10 queued per mailbox) that determine whether the tool can be used at all.

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 non-readOnly, idempotent, non-destructive, so the bar is lower; the description still adds value by stating it returns the flags afterwards and explaining Gmail-specific semantics (flag = star, applies under every label). This is genuine context beyond the structured fields.

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

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

Three tight sentences: action, required inputs, return value plus platform nuance. Front-loaded and zero 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?

Output schema exists and the description confirms it returns the flags afterwards, so return values need no elaboration. Inputs, constraints, and Gmail behavior are all covered for this simple mutation tool.

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

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

Schema coverage is 100%, so baseline is 3. The description earns more by adding a constraint not encoded in the schema: at least one of flagged/seen must be set, plus the star/label semantics of the flag.

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 specific verbs (flag/unflag, mark read/unread) against a specific resource (a message), making it trivially distinguishable from siblings like move_message and trash_message. An agent can pick 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?

Explains the prerequisite flow (get the message id from search_messages) and enforces that at least one of flagged/seen must be supplied. It does not name explicit when-not conditions or alternatives, but the operating context is clear.

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

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

Adds substantial context beyond the annotations: nothing is permanently deleted or expunged, the message receives a new id in Trash, and on Gmail it leaves every label including All Mail. The new-id disclosure is operationally critical and appears nowhere in the annotations or schema.

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

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

Front-loaded with the core semantic (soft delete), then each following sentence adds a distinct fact: recoverability, id source, id change, no-op case, Gmail behavior. No filler.

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

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

A mutation tool with annotations covering safety and idempotency, an output schema covering returns, and a description that closes the remaining gaps (recoverability, id mutation, provider-specific side effect). Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description only restates that message_id comes from search_messages. It does add the post-condition that the id changes in Trash, but that is an outcome rather than parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource plus the exact semantics: 'move it to the Trash folder, where it can still be recovered.' This clearly separates it from a hard-delete or from move_message, which relocates to arbitrary 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?

Tells the agent where the id comes from ('from search_messages') and covers the no-op case ('A message already in Trash is left as it is'). It doesn't explicitly name move_message as the alternative for non-Trash relocation, so routing between the two 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.