MCPEmails

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

Annotations already provide idempotentHint, readOnlyHint, and destructiveHint, and the description adds meaningful behavior: the effect ('never delivered'), the accepted decision value ('only reject'), and the auth limitation for approvals. No contradiction with annotations exists.

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

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

Two tight sentences with the core action and outcome front-loaded. The second sentence adds the constraint and alternative without excess. Every phrase contributes.

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, well-annotated mutation tool with an output schema, the description covers the action, the only accepted decision, and the alternative for approving. It does not explicitly state the post-rejection state of the approval, but the schema and output schema fill the remaining context.

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 decision constraint that already appears in the schema ('decision accepts only reject') without adding new parameter context such as where approval_id comes from or how note is used.

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

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

The description opens with a specific verb and resource: 'Reject a send that is waiting for human approval, so it is never delivered.' It states the outcome explicitly and immediately distinguishes itself from approval actions by noting 'Approving is deliberately not available over MCP.' The title reinforces the scope.

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 clearly establishes when to use the tool (to reject a pending approval) and explicitly warns when not to (approving requires a signed-in browser session with owner/admin). It does not name a sibling MCP tool as an alternative, but the boundary between this tool and the browser review flow is explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds useful behavioral context beyond annotations: the tool fetches the full contents including the body, and approval cannot be performed from this tool. It does not introduce any contradictions.

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, each earning its place: the first establishes the operation and result, the second emphasizes read-only behavior, the third clarifies the boundary and points to the alternative. Highly concise and well-structured.

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 single documented parameter, the output schema, and the comprehensive annotations, the description provides everything an agent needs to call this tool correctly. It covers the purpose, the read-only nature, the approval limitation, and the source of approval_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 description coverage is 100%, with the single parameter approval_id already described as returned by a gated send with status 'pending_approval'. The description does not add new parameter-level semantics, but it also does not need to because the schema carries the load.

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 uses the specific verb 'Fetch' and clearly identifies the resource: a send waiting for human approval, including its body. It also distinguishes itself from the approval action by stating 'Read-only' and 'Approving is not possible from here', which differentiates it from approval_decide and related siblings.

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 explicitly states when to use the tool ('so it can be shown in the review card') and when not to use it ('Approving is not possible from here'). It even provides the alternative path: 'it requires the signed-in review page linked as review_url.' This gives clear routing guidance.

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

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

The description usefully explains that this sets a delivery time without queuing anything, and only applies to an approved message going out. Annotations already signal idempotent/non-destructive; the description adds the sequencing behavior and the precondition that approval must happen first.

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

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

Two sentences, front-loaded verb and resource, no filler. It states what it does, the key constraint, and a clarifying behavior all in compact form.

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 tool with full schema coverageavorite and an output schema, the description fully covers when to use it and what it does not do. Nothing essential 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 description coverage is 100% for both parametersais4, and the description mainly restates the schema's future-time constraint for send_ataiman. It doesn't add meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description uses a specific verb plus resource: 'Set the delivery time of a send that is waiting for human approval.' It clearly separates this tool from general scheduling by emphasizing it applies only to sends in the pending-approval state. This distinguishes it from siblings like schedule.

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 states exactly when the tool applies: to a send waiting for human approval qui n'est pas encore programmé, and it clarifies that nothing is queued until approved. It lacks an explicit 'use X instead' exclusion, but the context is clear enough that an agent can identify this as the approval-specific scheduling path.

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 indicate readOnlyHint=false (mutation) and idempotentHint=true (safe to retry), which description does not contradict. The description adds useful behavior: the message still needs approval, reviewer sees edited version, and subject can only be set on certain operations. This satisfies the bar.

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 concise sentences, each providing essential info without fluff. Front-loads the purpose, then critical behavior, then a constraint on subject. No waste.

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

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

Output schema exists, so return values are covered. Description covers the key preconditions and side effects. Lack of explicit prerequisites (e.g., permission to edit) is minor, so a 4 is fair.

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

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

Schema coverage is 100% with detailed descriptions for all parameters, including the regeneration rule for body_text. The description adds minimal parameter detail beyond the schema, so baseline 3 is appropriate.

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

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

Clear verb 'Change' with resource ('subject or body of a send') and explicit context of pending approval. It distinguishes from siblings like approval_decide and approval_review by focusing on editing rather than approval action.

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?

States when to use: for sends waiting for approval, must be approved afterwards, and reviewer sees edited version. It does not explicitly name alternatives or when not to use, but the context is fairly 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 give idempotentHint=true and destructiveHint=false, and the description reinforces this with 'Nothing in the mailbox changes'. It also adds new context about the 15-minute expiration and that cancellation 'records the decision', which goes beyond what the annotations state.

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

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

The description is only a few sentences, with the essential action and consequence front-loaded. Every sentence provides a relevant detail: the decline action, the input scope, the non-mutating nature, and the expiry alternative. No filler or extraneous 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?

Given that the tool has a single parameter, an output schema, and annotations covering idempotency and safety, the description provides enough to call the tool correctly. It covers what action is taken, what won't change, and how the cancellation is recorded, leaving no critical gap for this simple use case.

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 only parameter, plan_id, is already fully described as a UUID returned from a bulk preview. The description only says 'Takes only the plan_id' which does not add new semantic 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 description uses the specific verb 'Decline' and names the resource ('a previewed bulk delete or move'), then adds the consequence 'so it can never run' and distinguishes itself from bulk execution. It also clarifies the single input with 'Takes only the plan_id', which fully separates this from bulk_execute.

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 provides clear context: use it to decline a preview operation before it runs. It also explains an alternative, 'would also expire on its own after 15 minutes', implying the choice to cancel now or do nothing. However, it does not name a sibling like bulk_execute explicitly, so it lacks the exclusions 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?

Beyond the annotations' destructiveHint=true, the description discloses crucial runtime behavior: plans run at most once, expire 15 minutes after creation, and cannot be altered at execution time. This tells the agent about idempotency and time-sensitivity without relying on inference.

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

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

Three tightly packed sentences deliver the action, the single-parameter constraint, immutability, once-only execution, and expiration. There is no filler or redundant restating of the 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 one-parameter tool with a full output schema and annotations, the description covers all operational essentials: what it runs, where the plan_id comes from, immutable scope, idempotency limits, and expiration. Nothing critical 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?

Even though the schema already documents plan_id at 100% coverage, the description adds essential meaning: the plan_id fully determines the set of affected messages, the decisions were frozen at preview time, and no other parameters are accepted. This clarifies why a single parameter is sufficient.

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 ('Run') and a specific resource ('a bulk delete or move that was previewed as a plan'), which clearly distinguishes it from bulk_cancel and other bulk-related tools. It also specifies that the affected messages were already decided, so there is no ambiguity about what execution means.

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 clearly indicates when this tool should be used: after a bulk preview has been created, with only the plan_id needed. It also gives exclusions such as 'cannot be changed here' and 'runs at most once,' but it does not explicitly name an alternative tool such as bulk_cancel for cancellation scenarios.

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 read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond that: the scan is bounded and header-only, message_count is window-limited, paging requires identical arguments, and total may be an estimate when the scan window is full. It also discloses that display names come from untrusted mail headers and are marked untrusted_content: 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?

The description is front-loaded with purpose and the key caveat that there is no stored contact list. It is dense, but every sentence carries necessary behavioral information about scan scope, paging, estimates, or untrusted 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 read-only search tool with an output schema and full schema descriptions, the definition covers the important non-obvious behavior: recent-window scanning, cross-inbox scope, paging rules, estimate flags, and untrusted display-name data. Nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents query matching, inbox_id behavior, inbox as an address alternative, limit, and offset. The description mostly restates those semantics rather than adding new parameter-level meaning, 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?

The first sentence gives a specific verb and resource: 'Find people by name or email fragment.' It also immediately clarifies that this is not a stored contact list but a mail-header scan, which distinguishes it from ordinary contact-list lookup and from message search.

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 explains a clear use case: omitting inbox_id scans every accessible inbox and answers cross-inbox questions like who the user emails most about a topic. It does not explicitly name a sibling alternative or state when-not to use it, so it falls 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 only say this is a destructive, open-world write; the description goes far beyond, disclosing IMAP draft_id invalidation on each update, that update is a partial merge (omitted body kept), that a new body preserves the quoted original, signature embedding rules on create/update-send, the 10 MB attachment ceiling, and that a reply draft's results are marked untrusted_content. It also explains the draft editor card can mutate/send/discard the draft out-of-band, which is material behavior an agent could not infer from the schema.

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

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

Purpose and the primary alternative are front-loaded in the first sentence, and almost every sentence carries distinct operational information. It is dense and reads as a single block with many interleaved topics (permissions, cards, attachments, quoting), so topic grouping could be tighter, but little is 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 an 18-parameter, five-action mutation tool, the description covers the action semantics, permission model, failure modes (stale draft_id, draft_changed), side effects (signature, card edits), and cross-tool relationships. An output schema exists, so return values need not be explained.

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 earns an extra point by explaining cross-parameter semantics the schema only hints at — what 'update' merges versus replaces, that attachments on 'update' are additive, and that send requires a recipient. It stops short of covering confirmation/base_revision/follow_up_days beyond what the schema already says.

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 set over a specific resource ('Create, update, send and delete unsent drafts in one inbox') and immediately distinguishes itself from the sibling email_compose ('email_compose sends now'). An agent knows exactly what class of work this tool handles.

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 when-to-use condition is given ('when the user wants to review or edit a message before it goes out'), plus a named alternative for the send-now case. It also routes follow-up needs to draft_read and draft_list, and spells out per-action requirements (reply needs read:email, send needs send:email, rest manage:drafts).

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: it declares the change is a display preference only, that draft results keep coming back as plain text, that hidden:false reverses it, and that workspace scope requires an owner/admin role. The annotations only say readOnlyHint=false, destructiveHint=true and idempotentHint=true; the description supplies the missing side-effect scope, reversibility, and authorization requirements.

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

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

Front-loaded with the action, then reversal, then scope/permission caveats. Every sentence carries information, though the scope/permission material is split across two sentences and could be tightened 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?

Output schema exists, so return values need no explanation, and the annotations are supplemented rather than repeated. For a 4-parameter preference toggle, action, reversal path, scope semantics, and role requirements are all covered.

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 schema already documents all four parameters and the baseline would be 3. The description adds genuine semantics on top: hidden:false re-enables the card and works at either scope even while the card is hidden. It does not add anything about inbox vs inbox_id resolution 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 (hide/show) on a specific resource (the in-chat draft editor card), plus the two scopes it can act on. An agent can immediately distinguish it from draft_editor_save or draft_list, which manipulate content rather than display state.

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?

Frames use with 'when the user asks for that' and clarifies that drafts, sending and every other tool are unaffected, implicitly steering the agent away from using this for content changes. It does not name a sibling tool as the alternative for any adjacent task, so it stops short of full when/when-not routing.

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

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

The annotations declare idempotentHint=true, but the description says on IMAP the save returns a NEW draft_id and the old one stops resolving, so an identical repeated call would not have the same effect. This contradicts the annotation and triggers the annotation-contradiction rule despite the description otherwise adding rich behavioral detail.

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 dense but front-loads the purpose and proceeds through important caveats. Every sentence carries useful behavioral information, though the paragraph could be slightly 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 complex save operation across IMAP, Gmail, and Outlook, the description covers no-signature behavior, no sending, new draft_id behavior, rebuild limitations, and refusal conditions. With an output schema present, it need not explain return values.

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 each parameter's meaning, including omit-to-keep semantics. The description adds only a blanket optionality rule, which is largely duplicative and slightly imprecise against the required draft_id.

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: saving fields edited in the draft editor. It distinguishes from the draft tool's update behavior and clarifies that nothing is sent, so an agent can identify its role 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 clear context: use it after a person edits a draft in the draft editor. It also contrasts with the draft tool's update when a body is supplied, but does not explicitly enumerate alternatives or when-not-to-use beyond refusal 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?

Beyond the readOnly/idempotent annotations, it discloses non-obvious behavior: results omit the body, the list can go stale because the user can edit/save/send in the draft editor card with no notice, and reply drafts return untrusted_content: true. Pagination via limit (max 50) is implied. This is exactly the kind of 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 return shape, then the ID handoff, then the staleness caveat. Dense with useful content and no filler, though the staleness/untrusted-clause sentence is somewhat convoluted and could be split or 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?

For a read-only list tool with a full schema, an output schema, and annotations, this covers everything an agent needs: what comes back, what does not (body), how to get it (draft_read), how IDs chain to write tools, and the freshness caveat.

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 inbox, inbox_id and limit are already documented in the schema. The description adds no syntax or defaulting guidance for them, and its only ID discussion (draft_id) concerns results, not inputs. 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?

Opens with a specific verb+resource and scope: 'Return draft messages saved in the inbox's Drafts folder.' It immediately contrasts with the sibling draft_read ('no body: draft_read returns one draft's text'), so an agent can tell the list tool apart from the single-draft reader 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?

Routes clearly: use this to enumerate drafts, use draft_read for a body, and the returned draft_id feeds draft_read and draft (action 'update'/'send'/'delete'). It also warns the user may mutate drafts outside the tool, implying a re-read via draft_read. It does not explicitly exclude use for searching (e.g., email_search_and_move), which is the only gap.

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

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

Adds a great deal beyond the readOnly/idempotent annotations: required scopes ('read:email' plus 'manage:drafts'), the concurrency hazard that the user may edit or send with no notice, the specific 'already sent' response, the host's one-line summary instead of opening a second editor, and the untrusted_content flag. This is exactly the kind of context annotations cannot convey.

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

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

Front-loaded with purpose and return values, then the cautions. It is dense and one sentence ('so this read is its current subject, recipients and sent state') is awkwardly worded, but nearly every sentence carries operational value.

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 and full annotations already present, the description still covers the gaps that matter: auth scopes, stale draft_id risk, send-race behavior, and untrusted content flagging. Nothing an agent needs to call it safely 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 draft_id instability-on-save caveat is already in the schema, so the description adds little parameter-specific detail. Its note about the read reflecting 'current subject, recipients and sent state' is behavioral rather than a parameter clarification, 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 and resource ('Get the current text of one unsent draft') plus the fields returned, which separates it from draft_list (listing) and email_read (a received message). The concrete scenario ('before revising a draft the user edited in the draft editor card') makes the scope unmistakable.

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

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

Gives a clear trigger case (re-reading a draft after the user edited it) and implicitly excludes listing via the 'one draft' framing, but never explicitly names draft_list or email_read as the alternatives an agent should consider 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?

Goes well past the annotations (destructiveHint, openWorldHint) by disclosing that the signature is auto-appended and where, that reference attachments are moved server-side so bytes never pass through the conversation, that batch forwards report per-message results so partial failure is visible, and — most importantly — that reply/forward outputs carry untrusted_content: true because recipients/subject come from the original's headers, while a plain send does not.

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 verb and resource in the first clause, then progressively narrower caveats. It is one dense paragraph with mild repetition against the schema, but every sentence carries real behavioral information and none is filler.

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

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

For a 21-parameter, destructive, open-world tool with a full output schema and 100% schema coverage, the description covers the cross-cutting behaviors an agent would otherwise miss (signature, attachment reference form, batch forward, untrusted-content flagging). It does not explain the confirmation-refusal flow or the destructive consequences implied by destructiveHint: true.

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 rather than extends parameter meaning — the signature-placement and header-derivation notes mirror what include_signature, to, and subject already document in the schema — and adds little new syntax or constraint detail.

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 set and resource: 'Send new mail, reply, or forward from one inbox,' and then differentiates the three actions by behavior. An agent can tell this is the outbound-send tool rather than a drafting tool, though it never names the sibling (draft) it must not be confused 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?

Gives clear situational context: 'reply and forward derive their subject and recipients from the original sender's headers,' 'pass include_signature: false' for a terse reply, and forward accepts up to 50 message_ids in one call. It stops short of explicit exclusions (e.g., when to use draft instead of sending).

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 (destructiveHint, idempotentHint), the description discloses that deletions go to Trash and remain recoverable, that permanent: true is irreversible, and that the delete:email scope is required. It also explains the partial-success signal (has_more) for bulk deletes — real behavioral context an agent cannot get from structured fields 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?

Four short sentences, no filler, and the most dangerous fact (Trash by default, irreversible with permanent) is front-loaded right after the scope statement. Every clause carries operational weight.

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 covering the safety profile and an output schema covering returns, the description supplies the remaining essentials: recoverability, the auth scope, and bounded-search semantics. It could go further by noting which parameters apply to which action (message_id vs message_ids vs filters), though the schema's action description partly covers that.

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 21 parameters are already fully documented; the description only deepens understanding of limit/permanent/has_more, which the schema largely covers too. Baseline 3 is appropriate since the schema does the heavy lifting and the description adds little parameter-level detail of its own.

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 and resource ('Delete messages') plus a scope constraint ('in one inbox') that separates it from sibling tools like email_search_and_move or email_organize. The three-action model (delete, delete_batch, search_and_delete) is named, so an agent knows exactly which flavor of deletion it is invoking.

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 clearly states the condition that selects the irreversible path (permanent: true) versus the recoverable default, and explains that search_and_delete is capped by limit, with has_more: true signalling leftover matches. What's missing is explicit routing against siblings (e.g., when to delete versus move/organize), so the agent must infer that from tool names.

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 mutation/safety profile; the description goes far beyond by stating that every action is reversible and how (move back, move to Inbox, opposite flag, copy leaves the original). It also discloses connector-specific semantics: capabilities.copy on inbox_list, Gmail API having no copy, label-based moves on Gmail, and Trash/Spam clearing on restore — none of which the annotations convey.

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 reversibility rules are front-loaded and every clause is substantive, but the copy/connector paragraph is long and partly restates what the action enum already documents, costing some tightness.

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, full annotation coverage, and 100% parameter documentation, the description still supplies everything an agent needs to pick the right action and predict side effects — reversibility, permission scope, and connector caveats.

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 adds the missing semantic link that message ids originate from email_read and reiterates the copy capability gate that constrains the copy/copy_batch actions. It adds real meaning but much of the connector detail is already duplicated in the action enum's schema description.

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

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

States a specific set of verbs (move, copy, flag, archive) and the resource (messages named by message_id in one inbox), then explicitly contrasts with email_search_and_move and email_delete. An agent can distinguish it from every sibling 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 explicit routing: use this for a list of ids, use email_search_and_move when a whole search result must be relocated, and use email_delete for deletion. It also names prerequisites — ids come from email_read, and the manage:folders scope is required.

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 readOnlyHint/idempotentHint already declaring the safety profile, the description earns credit by disclosing non-obvious result behavior: pages are single, implicit termination is unsafe, and long bodies are windowed with body_truncated/body_next_offset. That continuation contract is not derivable from the annotations and is exactly the kind of trap this description prevents.

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 dense sentences, front-loaded with the purpose before the paging contract. Nothing is wasted, though the body-windowing sentence arrives abruptly and its pronoun reference ("the same way") requires the reader to map it back to the paging rule.

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?

Because the schema documents every parameter and an output schema exists, the description need not explain return values, and it correctly spends its budget on the paging and truncation contract. The missing piece is routing relative to siblings such as email_search_and_move, which no structured field covers.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only clarifies semantics for offset and body_offset by tying them to the returned next_offset/body_next_offset, leaving the other 26 parameters entirely to the schema.

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

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

The opening sentence names the resource and three concrete verbs (read, list, search) scoped to a single inbox, which is far more specific than a title restatement. It stops short of differentiating the tool from the sibling email_search_and_move, and it never surfaces the remaining action values (read_batch, attachment, extract, original) that the schema enum carries.

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 guidance is limited to the paging loop: "when the response says has_more, call again with the returned next_offset" and the termination rule "Only has_more: false means you have seen everything." There is no guidance on choosing this tool over email_search_and_move or folder_list, so the agent must infer when to reach for 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 cover destructive/idempotent/readOnly, but the description adds real value beyond them: server-side atomicity so no id goes stale, the Gmail label add/remove semantics, the 500 default cap with has_more signaling leftovers, the required manage:folders permission, and the return shape. It does not spell out partial-failure behavior beyond 'succeeded/failed counts', 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?

Front-loaded with the core action and scope, then the risk warning, then the routing alternative and limits. It is dense and mostly earns its length, though the parenthetical field list and the Gmail label detail could be trimmed slightly without losing selection-critical information.

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

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

For an 18-parameter destructive bulk mutation this covers the essentials: what is affected, permission requirement, truncation behavior, continuation route, and platform-specific move semantics. The output schema handles return values, so the brief mention of counts is sufficient.

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 still adds framing by characterizing the structured search fields as provider-agnostic and translated server-side, and by labeling `query` a raw escape hatch. It also ties `limit` to the has_more continuation behavior, which is semantic context the schema's per-property text does not state.

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 key mechanism ('Move every message matching a search into a destination folder, in one server-side operation'), and immediately contrasts itself with email_organize by noting it acts on filters rather than chosen ids. An agent can distinguish it from every sibling 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 names the alternative (email_organize with 'move' or 'move_batch') and the condition that selects each: this tool for filter-matched bulk moves, email_organize for messages already listed by id. It also explains the follow-up path when has_more is true, giving a complete selection and continuation rule.

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 annotations: annotations only flag destructiveHint=true, while the description specifies that deletion is irreversible and, on Gmail, strips the label from every message carrying it. It also names the required scope (manage:folders), which annotations cannot express.

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 dense sentences, front-loaded with the action set and the highest-risk fact (irreversibility) appearing early. The nested parenthetical about 'label' is slightly compressed and costs a bit of readability.

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, so return values need no explanation. The description covers the cross-provider naming trap, permissions, destructiveness detail, and where to get folder_id — everything needed to invoke 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 100%, so the baseline is 3, but the description adds real value by explaining why the arguments say "folder" while Gmail uses "label" (type: 'label'), preventing a wrong-model assumption. The cryptic "type: 'label'" phrasing and lack of per-action parameter mapping keep it off 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 set + resource ("Create, rename and delete mailbox folders") and immediately disambiguates the folder/label terminology across providers. An agent knows exactly what operations are available 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?

Points to the sibling that supplies prerequisites ("folder_list returns the folders that exist and the folder_id these actions take") and states the permission gate. It stops short of saying when to prefer this over nearby mutators like email_organize, which also touch labels, so no explicit exclusions.

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, closed-world, so the bar is lower, and the description still adds real value by explaining that folder names are free-form, possibly attacker-chosen (shared/delegated/migrated mailboxes), and therefore flagged untrusted_content: true. That is genuine safety context beyond the annotations; it stops short of covering pagination, ordering, or provider quirks.

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 action and having the trust warning placed last where it can't be missed. The middle sentence enumerating return fields is mildly redundant given an output schema exists, but it stays 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 zero-required-parameter read tool with full schema coverage, full annotations, and an output schema, the description covers scope, the folder/label variant, downstream consumers, and the untrusted-content caveat. Nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100% and both parameters (inbox, inbox_id) are documented in the schema, so the baseline is 3. The description only implies inbox scoping ('for an inbox') and adds no format, precedence, or default behavior beyond what the schema already states.

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

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

Opens with a precise verb + resource + scope: 'List all folders (or labels, for Gmail) for an inbox,' and explains the label-vs-folder distinction. It does not explicitly separate itself from the sibling 'folder' tool, so an agent still has to infer that one lists and the other presumably manages a single folder.

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 through the note that returned names/ids feed email_read (action 'list') and email_organize (action 'move'), which tells the agent this is the discovery step before those calls. However, there is no explicit 'use this when / use X instead' statement and no mention of when NOT to call it (e.g., already-known folder id).

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 real behavioral context: scope is limited to the API key's permitted inboxes, and it explains the provider-vs-service ambiguity that would otherwise cause misreads of the result. It does not mention ordering or pagination, 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?

Front-loads purpose and the inbox_id payoff, then explains the data model. The closing Gmail app-password example restates the preceding sentence's provider/service point rather than adding new information, which is mild redundancy.

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

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

Output schema exists, so return values need little explanation, yet the description still characterizes the fields an agent will inspect. Given four optional filters and a simple read, the definition is complete enough to invoke correctly; only the absence of list-ordering/volume expectations leaves a small gap.

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

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

Schema coverage is 100% and the schema already spells out the provider/service distinction and the include_capabilities behavior. The description reinforces the trickiest semantic point (service is the brand, provider is the connector) but adds little beyond what the schema documents, so the baseline 3 applies.

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

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

States a specific verb and resource ('List every inbox (mailbox or account)'), plus the auth scope ('this API key may use') and the key output ('the inbox_id the other tools take'). Clear enough to distinguish from folder_list or draft_list as an account-discovery tool.

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

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

The sentence 'It returns the inbox_id the other tools take' implicitly routes the agent here before calling inbox-scoped tools, and the filter parameters carry 'Omit for all of them' guidance. No explicit when-not or named alternative is given, but the usage context is clear for a discovery tool.

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

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

Beyond the annotations it discloses genuinely useful behavior: reminders run server-side with no model in the loop, a reply auto-clears a follow-up, the server restores snoozed mail at the target time, and done vs cancel differ in where the message ends up. It also rules out an expected side effect with "Nothing here sends mail." It does not flag that done/cancel are irreversible given destructiveHint=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?

It opens with the defining property (survives chat close, no model in the loop) before the action breakdown, so it is front-loaded. The action sentences are dense but each carries a distinct rule; only the repeated quoted action names cost a little 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?

For a 10-parameter, four-mode tool with full schema coverage, annotations, and an output schema, the description covers the remaining unknowns: id provenance, per-action parameter requirements, lifecycle effects on the message, and the no-send guarantee. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds something the flat schema cannot express: which parameters belong to which action (follow_up takes message_id plus days or due_at; snooze takes message_id, until, optional condition and folder; done/cancel take `id`). That conditional grouping is real added meaning.

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 names the resource (server-side reminders) and enumerates the four concrete operations (follow_up, snooze, done, cancel) with a one-clause definition of each. It also separates itself from the sibling reminder_list by saying that list is where due follow-ups surface and where `id` comes from.

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?

Each action carries an explicit selection rule — follow_up tracks an unanswered sent message, snooze pulls a message out of the inbox until `until`, done stops but leaves it, cancel stops and restores it now. It stops short of routing against adjacent siblings like schedule or approval_schedule, so the when-not-to-use side is only partially covered.

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 covered. The description adds context annotations cannot carry: results are marked `untrusted_content: true` because subjects/addresses are mail-derived, which is important behavioural information for an agent handling the output. It stops short of describing ordering across modes or pagination behaviour beyond the limit default.

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 the mode semantics, then the untrusted-content caveat, then the sibling handoff — a sensible order with no filler. It is dense (three sentences packed with clauses) but every clause carries information.

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

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

With an output schema present, return shape needn't be documented, and the description still flags the untrusted-content marking, which an agent must know. Combined with the mode semantics and the pointer to `reminder`, an agent has what it needs to call this correctly; only cross-sibling list disambiguation is absent.

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 would be 3, but the description genuinely enriches the `show` parameter by defining what 'due', 'upcoming' and 'all' actually return, including that 'all' includes finished items. It adds nothing for `kind`, `inbox`, `inbox_id` or `limit`, which are left entirely to the schema.

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

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

The first sentence states a specific verb and resource ('List the follow-ups and snoozes the server tracks'), immediately scoping the tool to two reminder kinds. It also distinguishes itself from the sibling `reminder` tool by noting that `reminder` takes an id from this list to mutate a record, so an agent can route 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?

The description explains the three `show` modes and what each surfaces ('due' = past due with no reply plus failures; 'upcoming' = pending, soonest first; 'all' = everything, finished included), which is genuine selection guidance. It also hands off to `reminder` for mutation, but does not contrast with adjacent list siblings such as `schedule_list` or `draft_list`.

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/open-world annotations, the description discloses validation behavior, the ~60-second dispatch window, the attachment format restriction, the required schedule:email scope, and the absence of an untrusted_content flag on cancel results. This is rich behavioral context 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?

The description is dense but front-loaded, starting with purpose and the key distinction from email_compose before moving into constraints. Some details duplicate schema constraints, but the length is justified by the tool's complexity and the paragraph remains focused.

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 15-parameter tool with an output schema, the description covers the important decision points: action semantics, timing requirements, cancellation limits, attachment form, authentication scope, and invalid-message handling. Remaining field-level details are well covered by the schema.

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

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

Schema description coverage is already 100%, so the baseline is 3, but the description adds meaningful semantics: send_at must include a timezone offset and is not second-precise, id comes from schedule_list, and the attachment reference form belongs to email_compose rather than this tool.

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: queueing a message for future delivery or cancelling it. It explicitly distinguishes this from email_compose by saying email_compose sends now while this tool is for a time the user names.

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 when-to-use and when-not-to-use guidance: use email_compose for immediate sends, use this for future sends, and use schedule_list to find the id needed for cancellation. It also states that only pending sends can be cancelled.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real value beyond them: the status filter applied server-side, the sort order (earliest first), and the hand-off contract where the returned id is the cancel key. It does not discuss result volume or paging beyond the schema's limit parameter.

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

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

Three sentences, front-loaded with purpose and scope, then filtering, then the id contract. Every sentence carries information an agent needs and none is redundant.

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

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

For a read-only list tool with an output schema and full parameter coverage, the description supplies everything an agent needs: what is returned, in what order, how to narrow it, and how the result feeds the cancel path.

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

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

Schema description coverage is 100%, so all three parameters are already documented and the baseline is 3. The description only says 'optionally filter by inbox' and does not disambiguate the two distinct filter parameters (email address vs. inbox_id UUID), so it adds little 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 ('List pending scheduled email sends') along with the exact status filter ('pending' or 'sending') and the returned ordering. It also distinguishes itself from the write-side sibling by naming the schedule tool's 'cancel' action as the consumer of the returned 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?

Implies the use case clearly: fetch pending sends, optionally narrowed by inbox, and note that the returned id feeds the cancel action. It never states when NOT to use it or why one would pick it over bulk_cancel or draft_list, so it stops short of full alternative routing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds real behavioral context by stating that the signature is appended server-side on send/reply/forward/draft/scheduled messages and that source can be null when unset. It does not cover pagination or error behavior, but for a single-object read that is minor.

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 in the first clause, and the second sentence about server-side appending is genuinely useful. The middle enumeration of return fields is somewhat redundant given an output schema exists, but it is compact and not padded.

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 covering safety and an output schema covering return shape, the description's job is largely done; it goes further by enumerating key return fields and explaining where the signature is applied. The only real gap is explicit routing guidance versus siblings like signature_set.

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 inbox and inbox_id are already documented as alternatives and inbox_id as optional with a single inbox. The description adds no additional parameter semantics, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Read the email signature configured for an inbox') and immediately distinguishes itself from the sibling signature_set, which is the write counterpart. An agent can tell what it 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?

Usage is implied by the verb 'read' and the sibling naming (signature_set), but there is no explicit 'use this when...' statement, no mention of prerequisites, and no guidance on the two identifier alternatives beyond what the schema already says. Minimum viable.

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 (which already declare mutation, destructive and idempotent), the description discloses real behavioral consequences: setting a signature marks its source 'manual' and permanently overrides Gmail auto-import, empty strings clear values, and signature_enabled=false disables without deleting. It does not cover permissions/auth or rate limits, but the permanence and disable-vs-delete distinctions are valuable non-obvious 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?

The purpose is front-loaded in the first clause, and the remaining sentences are dense with parameter-specific rules rather than filler. It is somewhat long and repeats a few schema-stated defaults (e.g. signature_enabled default true), costing it the top score, but nothing is 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, no-required-params mutation tool with full schema coverage and an output schema, the description covers clearing semantics, derivation, the enable-without-delete path, reply-mode behavior, and the permanent manual override. An agent has everything needed to invoke this correctly without opening the schema.

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

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

Schema coverage is 100%, so per-field meaning is already documented and a 3 is the baseline. The description adds cross-parameter behavior the schema states only piecemeal: either/both fields accepted with the missing half derived on send, and it spells out the reply-mode enum semantics ('always' signs every reply/forward, 'never' never does) that the schema only partially defines.

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+resource ("Set or update the email signature for an inbox") and clearly scopes the operation as a write on signature configuration. It is plainly distinct from signature_get, but it never names the sibling or any other tool, so it stops short of explicit 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?

It gives concrete usage context: pass either or both of signature_text/signature_html, use empty strings to clear, set signature_enabled=false to stop appending without deleting, and sender_name can be set alone. It does not state when to prefer this over signature_get or any exclusion/alternative path, so it is clear context without explicit routing.

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

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

Goes well past the annotations by spelling out the three per-sender outcomes: server-side one-click unsubscribe, a draft the user must send themselves ('nothing is ever sent'), and a returned link. It also discloses the destructive side effect ('backlog "archive" also archives what those senders already sent') and the 'each sender is asked once' idempotency guarantee, which concretizes the destructiveHint/idempotentHint flags rather than restating 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?

The behavior (what actually happens to each sender) is front-loaded and dense with useful content, but the mid-paragraph drifts into restriction and continuation detail before returning to the chat-vs-card usage note, which would read better grouped earlier.

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-modal tool with four parameters and an output schema, the description covers all the uncertainty an agent would have: who sends what, what is irreversible, how to resume, and which inputs are legal. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real constraints the schema lacks: only sender_keys from the associated plan are valid, and continue=true with the same plan_id resumes archiving. The backlog archive/keep distinction is largely already in the schema, so this falls 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?

Names a specific verb and resource ('Unsubscribe from senders picked from a subscriptions_scan plan') and immediately ties itself to the sibling tool that produces the input, so an agent can distinguish it from subscriptions_scan 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 states the two entry paths: the user picks senders on the scan's card, whereas this tool is for senders named in chat. It also explains the continuation case ('continue: true with the same plan_id finishes archiving') and the constraint that only sender_keys from the plan are accepted.

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, and the description adds genuinely new context: the plan expires after 60 minutes, which affects agent timing, and it explains the classification of unsubscribe methods. 'Changes nothing' is somewhat redundant with readOnlyHint but reinforces intent.

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?

Dense, front-loaded description with no wasted filler; the core action leads and the plan_id/expiry handoff follows. Slightly long single paragraph but every clause carries information.

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

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

For a read-only scan tool with a full output schema, the description covers purpose, output shape, safety, and the downstream handoff including plan expiry — everything an agent needs to call it and use the result.

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

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

Schema coverage is 100% with all four parameters documented in the schema (days, limit, inbox, inbox_id), so the schema carries parameter meaning. The description adds no additional parameter syntax or defaults beyond what's already structured.

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

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

States a specific verb and resource ('scan recent mail for newsletters and mailing lists'), plus the output shape (grouped by sender, unsubscribe method) so an agent can distinguish it from sibling subscriptions_cleanup 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?

Explains the workflow context: returns plan_id and sender_key values 'for subscriptions_cleanup', clearly routing the agent to the follow-up tool. It doesn't spell out explicit when-not conditions or alternative scan tools, but the scan→cleanup pairing is clear.

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