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

Annotations already declare readOnlyHint/idempotentHint, so 'Solo lectura' is largely redundant. However, since there is no output schema, the description adds real value by naming the fields returned (emails, organization, phone), though it omits behavior on unknown resource_name or any error/empty result case.

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 tight clauses, front-loading purpose, then returned data, then usage, then read-only nature. 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?

For a single-param, no-output-schema tool with full annotation coverage, the description covers purpose, usage and returned fields adequately. Missing only not-found/error behavior, a minor gap.

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

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

Schema coverage is 100% and already documents resource_name with the people/c123456 example. The description reinforces the format but adds no syntax or semantics beyond the schema, 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 pair (Obtiene el detalle de un contacto) and enumerates the returned fields (emails, organizacion, telefono), plus the identifier format people/c123. It is clearly distinguishable from the single contact sibling contacts_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?

'Usalo tras contacts_search para desambiguar' explicitly names the alternative and the condition that selects this tool over it, so no inference 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description reinforces read-only and adds a real disclosure the annotations do not: photos and notes are deliberately not exposed. It says nothing about how many results return, truncation, or how matching behaves (substring vs prefix), which would be the genuinely additive 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?

Three short sentences with no filler: purpose and input examples first, then the payoff and the use case, then the scope caveat. Front-loaded and immediately actionable.

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

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

No output schema exists, and the description compensates by naming the returned fields (name, primary email, organization) and the excluded ones (photos, notes). What is left uncovered is result-count behavior via max_results and any matching ambiguity, which matters for an agent deciding how many candidates it will get back.

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 50%: query is documented in-schema while max_results has no description anywhere. The description reinforces query semantics with example formats (a bare name or a full email), helping the agent choose input shape, but it never mentions max_results, its default of 5, or the cap of 20, so guidance on result breadth is missing from both sources.

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 and resource: search Google contacts by name or email, with the return surface (name, primary email, organization) stated up front. It is not explicitly differentiated from the closest sibling contacts_get or from gmail_suggest_recipients, which also resolve recipients, so the boundary with those is left to inference.

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

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

Gives a concrete usage context — resolving recipients before creating a draft — which tells the agent when to reach for it. It offers no exclusion or comparison, though, and the overlap with gmail_suggest_recipients (also a recipient-resolution tool) is never addressed.

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

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

Annotations already carry readOnly/idempotent/destructive=false, yet the description adds genuinely new behavioral facts: output is flattened plain text, access is scoped to documents the caller can already open, and the returned content is untrusted data that must not be followed as instructions (a meaningful prompt-injection warning). It stops short of noting size limits, truncation, or how tables/images are handled, and 'Read-only' merely restates the annotation.

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

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

Front-loaded with the action and return value in the first clause, then input forms, then the safety caveat. Four short sentences with no filler; every sentence 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 single-param, read-only tool with full annotation coverage and no output schema, saying it returns plain text is sufficient on the return side. Missing only operational detail such as size limits or partial-read behavior were a large doc encountered.

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?

One parameter at 100% schema coverage, so the schema already documents doc_url_or_id; the description's 'docs.google.com URL or a bare document ID' matches the schema text without adding format examples or edge cases. Baseline 3 for fully-covered params is correct here.

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

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

States a specific verb and resource ('Reads a Google Doc ... returns its plain text') with the output form named, and gives a concrete example ('a Gemini meeting-notes document'). No sibling in this server touches Docs content, so an agent can tell immediately this is the document-text tool rather than any gmail_* or contacts_* 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?

Implies usage via the example document type and the precondition 'you have access to', but never states when to reach for it versus another path (e.g. gmail_get_meeting_notes for the Gmail-side notes copy) nor when not to use it. Guidance is inferred rather than 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 the safety profile (not read-only, idempotent, not destructive), so the bar is lower. The description usefully adds that TRASH is protected and routed elsewhere, but omits other behavior that matters for a mutation tool: whether unknown label names are created or error, whether add/remove can be combined in one call, and permission requirements.

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

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

Two short sentences with the core action front-loaded and the safety caveat second; nothing is padded. It is arguably too terse given the undocumented parameters, but every sentence earns its place.

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

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

For a 4-parameter mutation tool with no output schema and zero schema descriptions, the definition leaves too much unexplained: label identifier format, message-vs-thread targeting, and what a successful response contains. Only the TRASH restriction is 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 description coverage is 0% for 4 parameters, so the description must carry the burden and largely does not. It never explains 'id', the 'type' enum (message vs thread, defaulting to message), or the label-name-vs-ID format and 100-item cap on add_labels/remove_labels.

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

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

The description states a specific verb and resource ('Adds and/or removes Gmail labels'), which is clearer than the bare tool name. It also carves out TRASH as out of scope, hinting at a boundary with siblings, but it never distinguishes itself from gmail_batch_modify_labels, the closest alternative.

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

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

One explicit exclusion is given: TRASH must go through gmail_trash_message. However, there is no guidance on when to use this single-item tool versus gmail_batch_modify_labels, nor on prerequisites such as whether the label must already exist.

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/openWorld=false, so the safety profile is covered. The description adds genuinely new context beyond that: audit queries are deliberately not themselves logged to avoid recursion, and the log never contains message bodies or secrets — both useful trust signals for an agent reasoning about what it will and won't see.

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, no filler, with the core purpose and filter list front-loaded and the caveats (no recursion, no bodies/secrets) trailing as supporting detail. Every clause earns its place.

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

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

With no output schema, the description should sketch the returned record shape (fields like tool_name, status, timestamp) and mention the max_results default/limit; it only hints at what's absent (no bodies/secrets). Directionally helpful but incomplete for an agent that needs to interpret results and page properly.

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

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

Schema description coverage is 0%, so the description must compensate, and it partially does by naming the three filter axes (tool_name, status, search). However, it doesn't explain what `search` actually matches against (tool names? free text?), the allowed status values, or that max_results exists with a default/cap, leaving real ambiguity.

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 (queries) plus specific resource (local JSONL audit log) and the filters it accepts. Nothing in the sibling list covers audit-log access, so an agent can immediately tell this is the telemetry-inspection tool rather than a Gmail mailbox 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 description implies the use case (inspecting tool-call history via tool_name/status/search filters) and clarifies it is read-only, but never states when an agent should reach for it versus other introspection paths, nor any exclusions. Usage is inferable rather than spelled out.

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-destructive, idempotent, open-world, non-read-only behavior, so the bar is lower. The description still adds real context beyond them: the 25-item cap is a hard operational limit and 'single audit entry' tells the agent the call is recorded as one unit, which matters for gmail_audit_query usage. It does not say what happens on partial failure or whether add/remove are applied atomically.

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 clauses, front-loaded with the action and its scope, no filler. 'Single audit entry' is slightly cryptic out of context but is the only borderline clause.

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 mutation batch tool with no output schema and 25% param coverage, the agent still lacks the response shape (success/failure per ID?), conflict rules between add and remove, and whether unknown label names are created or rejected. Adequate but with clear 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 only 25% — only `ids` is described in the schema — so the description must compensate. It does partially: 'messages/threads' maps to the `type` enum and 'label changes' implies add_labels/remove_labels, but it never explains the add-vs-remove distinction, label ID format, or what happens if both are supplied.

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 (label changes) with an explicit batch scope (up to 25 messages/threads), which distinguishes it from the single-item gmail_apply_labels. It never names that sibling, so the differentiation is inferred from 'batch' rather than asserted.

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?

One explicit exclusion is given with a redirect ('TRASH stays protected (use trash tools)'), which is genuine routing guidance. However, nothing tells the agent when to pick this over gmail_apply_labels, gmail_batch_trash, or gmail_restore_message, and the message-vs-thread choice is left unaddressed.

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 behavioral context beyond the annotations: operations are soft deletes, reversible via restore, require a reason, produce a single audit entry, and return per-item results. This meaningfully clarifies the destructiveHint=true and idempotentHint=true 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 short, front-loaded clauses with no wasted wording. The batch limit and reversibility appear immediately.

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

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

For a batch mutation tool with no output schema, the description covers the important operational facts: batch size, reversibility, required reason, audit behavior, and per-item results. It could still say more about partial failures or result shape.

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

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

Schema coverage is only 33%, so the description must compensate. It mentions the 25-item limit, messages/threads, and required reason, but does not explain the type default or reason length constraints, leaving meaningful gaps.

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 batch operation and resource: soft-deleting up to 25 messages/threads in one call. The batch scope distinguishes it clearly from the single-item gmail_trash_message sibling.

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

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

Gives clear usage context: use this for up to 25 items in one call, and a reason is required. It does not explicitly route single-item cases to gmail_trash_message or mention restore alternatives, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false and openWorld=true; the description's real contribution is the guarantee that no message is sent, which is meaningful safety context for a draft-creation tool. It says nothing about what is returned (draft ID?), duplicate-draft behavior on retry, or attachment/HTML constraints beyond what the schema states.

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

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

Two short sentences, front-loaded with the action and followed by the key constraint; nothing is wasted. The only markdown is that the brevity leaves obvious gaps rather than that any sentence 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 9-parameter mutation tool with no output schema and a third of schema coverage, the description is too thin: it omits return value, thread_id semantics, and any hint of the attachment/inline-image/HTML interplay that the more complex parameters require.

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

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

Schema description coverage is only 33% across 9 parameters, so the description is expected to compensate — yet it mentions no parameters at all. Required fields (to, subject, body) and the unexplained thread_id (apparently reply-threading) are left entirely to the schema, with thread_id carrying no description anywhere.

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

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

States a specific verb and resource (creates a Gmail draft) and adds a scope qualifier ('for human review'). It implicitly separates itself from gmail_send_draft and gmail_send_message_strict, though it never names the close sibling gmail_create_draft_with_drive_files.

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?

'For human review' plus 'never sends the message' implies the when: use this when a human should approve before sending. But it names no alternative tool and gives no explicit exclusion ('use gmail_send_draft when…', 'use gmail_create_draft_with_drive_files if attachments live in Drive'), leaving the routing 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?

The description adds useful behavioral context beyond the annotations: Drive files are downloaded server-side and never written to disk, at most 5 files are allowed, the operation is audited, and the draft is never sent. It does not mention auth requirements or rate limits, but the safety-relevant traits are well covered.

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 three short clauses, front-loaded with the core action and followed by the most important constraints. Every sentence carries useful information with no filler.

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

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

The description captures the critical limits and safety behavior, which is valuable for a tool with 7 parameters and no output schema. However, with very low schema description coverage, it remains incomplete about several parameters and does not describe the result of draft creation.

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

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

Schema description coverage is only 14%, and the description only adds meaning for drive_file_ids, noting IDs and the max of 5. It does not clarify the roles of to, cc, bcc, subject, body, or is_html, leaving most parameters without meaningful semantic guidance.

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

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

The description states a specific verb and resource: creating a Gmail draft with attached Google Drive files by ID. It also distinguishes this tool from plain draft creation by emphasizing the Drive attachment capability and from sending by stating it never sends.

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 intended use case is implied by 'Creates a Gmail draft attaching Google Drive files by ID', but the description does not explicitly say when to choose this over gmail_create_draft or gmail_send_message_strict. It also provides no exclusions or prerequisites.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent, closed-world. The description adds one genuinely new trait — "Audited" — signaling the operation is logged, which annotations do not convey. However, it omits critical behavior: whether a duplicate filter is rejected or created, whether forwarding requires a verified address, and whether label names or IDs are expected.

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

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

Two short sentences, front-loaded with the action. Nothing is wasted, though the trade-off is that brevity is achieved through omission rather than precision.

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 nested objects, zero schema descriptions, and no output schema. The description leaves unexplored how to express filter criteria, what label references mean, and what happens on conflict or failure — significant gaps for an A-tool to call correctly the first time.

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

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

Schema coverage is 0% and the two required objects nest 8 sub-fields total (add_labels, remove_labels, forward_to, from, to, subject, query, has_attachment) with no descriptions anywhere. The description's "criteria + actions" only restates the parameter names, adding no semantics such as Gmail query syntax, label-name-vs-ID conventions, or forwarding prerequisites.

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

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

States a specific verb and resource ("Creates a Gmail filter") and parenthetically names the two top-level inputs, which lets an agent distinguish it from gmail_list_filters and gmail_delete_filter in the sibling set. Clear but not embellished.

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

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

No guidance on when to create a filter versus listing, deleting, or editing one, and no prerequisites (e.g., that labels must exist first). The agent must infer context entirely.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description still adds real context: deletion is permanent/irreversible, it is scoped strictly to drafts, and the action is audited. It does not cover permission requirements or behavior when the draft_id does not exist.

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

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

Three short sentences with the destructive scope front-loaded and zero redundant text. Every clause carries distinct information: permanence, scope, required reason, and audit status.

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 destructive mutation with no output schema, the description covers the essentials: irreversibility, blast radius, mandatory justification, and auditability. Missing only error/permission behavior and how to obtain a valid draft_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 50%: 'reason' is documented in the schema (mandatory explanation), while 'draft_id' has no description anywhere. The description reinforces the mandatory reason but adds nothing about draft_id format or provenance, so it does not compensate for the coverage gap.

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

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

States a specific verb and resource ('Permanently deletes a Gmail draft') plus an explicit scope boundary ('drafts only — never touches sent mail'). It does not distinguish itself from nearby siblings such as gmail_trash_message or gmail_delete_filter, so the agent must infer that this is the hard-delete path for drafts.

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?

'drafts only' is an implied exclusion and 'Requires a reason' flags a prerequisite, which gives partial when-to-use signal. However, there is no explicit routing against gmail_trash_message (soft delete) or guidance to fetch the draft via gmail_get_draft/gmail_list_drafts first.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is carried by structured data. The description adds one genuinely new behavior: the operation is audited and records a reason. It does not say whether the delete is permanent or whether an admin permission is required.

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

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

Two short sentences with the destructive action and the audit trait front-loaded; no filler. It is arguably too terse rather than padded, which is a completeness problem rather than a verbosity one.

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 non-idempotent-looking yet destructive mutation with no output schema and zero schema coverage, the description covers the call mechanics but leaves gaps: permanence of deletion, how to discover filter_id, and the optional/defaulted nature of reason. Adequate to invoke correctly, not complete.

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

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

Schema description coverage is 0%, so the description has to do the work, and it does name both parameters semantically ("by ID" for filter_id, "with reason" for reason). It omits that reason is optional with a default of "filter no longer needed" and the 3-500 character bounds, so it only partially compensates.

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 ("Deletes a Gmail filter") plus the keying mechanism ("by ID"), which separates it from gmail_create_filter and gmail_list_filters among the siblings. It stops short of explicitly naming those alternatives, but the action is unambiguous.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no pointer to gmail_list_filters as the way to obtain the required filter_id. The only guidance is implied by "by ID" (you must already know the identifier).

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, and non-destructive, and the description reinforces that with "Read-only." It adds genuinely new behavior not in the annotations: a size guard ("Refuses payloads over MAX_ATTACHMENT_BYTES × 25") and the base64url encoding the caller must decode. It stops short of saying what happens on refusal (error shape) or whether attachments are inlined.

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 clauses, zero filler. Output format, downstream use, size limit, and safety profile are all front-loaded, with nothing repeated from 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 single-parameter read tool with no output schema, it covers the essentials: return encoding, how to interpret the bytes, a hard size ceiling, and confirmation of read-only behavior. A note on the refusal error or attachment inclusion would close the remaining 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% for the single message_id parameter, so the schema already carries the meaning and the baseline applies. The description adds no syntax hints for message_id (e.g., hex ID format) beyond what the schema states.

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

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

States a specific verb and resource ("Exports a Gmail message") plus the exact output format (raw RFC822, base64url), which implicitly distinguishes it from gmail_get_message_details and gmail_preview_message. It never names those siblings explicitly, so differentiation is inferential rather than stated.

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

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

"Decode to .eml for backup/forensics" implies when the raw form is the right choice, but the description never states when NOT to use it or points to the sibling that returns parsed message content. Usage is suggested, not routed.

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

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

Adds real context beyond the annotations: the forward includes a quoted attribution block, attachments are listed rather than re-attached, and the operation never sends. The annotations already say readOnlyHint=false, destructiveHint=false, and idempotentHint=false, but the description contributes the side-effect shape (a draft, not a send) and the attachment caveat.

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

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

Three short sentences with no waste: what it does, the two notable behavioural quirks, and the safety caveat. The most important fact (it never sends) is placed where it lands hard.

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 mutation-safety question well and explains attachments, but with no output schema the description should say what comes back (draft ID? message ID?) and whether forwarding the same message twice creates duplicate drafts given idempotentHint=false. Those gaps matter for a create tool.

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

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

Schema description coverage is only 40%, so the description is expected to compensate, and it does not. It says nothing about to/cc/bcc semantics, whether message_id must be a raw Gmail ID versus thread ID, or how comment interacts with the quoted block; the only param-related hint is the attachment behaviour, which maps to no parameter at all.

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

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

States a specific verb and resource: creates a draft that forwards a message, with a quoted attribution block. That is clearly distinct from gmail_reply_with_quote or gmail_send_message_strict in substance, but no sibling is named, so differentiation is inferential rather than explicit.

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?

'Never sends; review the draft before sending' implies the use case (prepare for review rather than send now) and hints that a separate send step follows. It never names an alternative tool such as gmail_create_draft or gmail_reply_with_quote, and gives no exclusions, so usage is only implied.

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

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

Goes well beyond the annotations: base64-in-memory (no disk write), a hard refusal above MAX_ATTACHMENT_BYTES, and an explicit untrusted-content warning. Annotations only say read-only/idempotent; the description supplies the size ceiling, the failure mode, and the security posture an agent needs.

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

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

Four short sentences, each carrying unique information: mechanism, lookup strategy, size guard, safety note. The key constraints are front-loaded with no filler.

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

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

With no output schema, the description correctly states the return form (base64), which is the critical completeness item. Minor gap: MAX_ATTACHMENT_BYTES is named but not quantified, and there's no mention of response shape/size expectations.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by explaining the lookup is by filename and why (ephemeral attachment IDs), which justifies the filename/mime_type/part_index triad instead of an ID parameter. It does not add syntax or format detail beyond that.

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 ('Downloads a Gmail attachment') and immediately distinguishes itself with the delivery mechanism ('as base64 without writing it to disk'). An agent can tell this apart from gmail_get_message_details or gmail_export_message without opening any schema.

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

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

Gives clear operating context: the part is located by filename, and Gmail attachment IDs are ephemeral and cannot be reused across calls, which tells the agent not to cache IDs. It lacks an explicit when-not/alternatives statement (e.g. versus export_message), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description restates 'Read-only' and adds useful return context (parsed headers, safe Markdown body, attachments), but it does not cover error behavior, permissions, or attachment representation.

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 a single front-loaded sentence with no wasted clauses. 'Read-only' is redundant with annotations, but the overall structure is tight and immediately useful.

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

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

There is no output schema, so the description's high-level return summary is important and mostly sufficient for a one-parameter read tool. It lacks details such as not-found behavior or how attachments are represented, which keeps it just short of fully complete.

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

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

Schema description coverage is 100%, and the only parameter, draft_id, is documented as coming from gmail_list_drafts. The description adds only 'by ID' and does not provide format or syntax details beyond the schema, 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 description states a specific verb and resource: fetches a Gmail draft by ID. It also names the return contents, and the ID scoping clearly distinguishes it from list/create/update/delete/send draft 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 phrase 'by ID' implies the tool should be used when a draft ID is already known, and the schema points to gmail_list_drafts as the ID source. However, the description does not explicitly name alternatives or state when not to use this tool versus gmail_list_drafts or gmail_get_message_details.

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 openWorldHint, so the safety profile is covered. The description adds meaningful behavior beyond them: it only returns providers and URLs and deliberately does not fetch external documents, which sets scope expectations.

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

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

Three short sentences with no filler; the extraction scope, the return shape, and the read-only nature are each covered once and front-loaded.

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

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

With no output schema, the description compensates by stating the return contents (providers and URLs) and the non-fetch behavior. For a one-parameter read tool this is nearly complete; only an explicit mention of the download alternative 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 thread_id parameter is fully documented in the schema. The description only echoes the thread-scanning context without adding format or constraint details, 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 ('Extracts') and precise resource ('meeting notes links ... from a Gmail thread'), and names the concrete link types (Google Docs from Gemini notes, Read AI reports). This clearly separates it from siblings like gmail_get_thread_summary or gmail_get_attachment.

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 clause 'without downloading external docs' implies that a doc-fetching tool (e.g., drive_get_doc_text) is the alternative when actual content is needed, giving clear contextual guidance. It stops short of explicitly naming that alternative or stating when-not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description's 'Read-only' is redundant but not harmful. It adds genuine context by disclosing that the body is returned as 'safe Markdown' (sanitized parsing) and that attachments are included in the response.

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 action and payload, then the workflow hint, then the safety trait. 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?

With no output schema, the description usefully summarizes the return shape and the annotations cover the safety profile. Minor gaps remain around attachment handling and error behavior for an invalid 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?

The single parameter message_id has 0% schema description coverage, and the description never clarifies that it is a Gmail message ID from search results. The implied link to gmail_search_messages gives a weak hint but does not compensate for the gap.

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 ('Fetches one message') and enumerates the parsed payload (headers, Markdown body, attachments). It is distinguishable from gmail_search_messages, though it never contrasts itself with gmail_preview_message or gmail_get_thread_summary.

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 after gmail_search_messages" gives an explicit workflow position and a named prerequisite tool. It does not state when not to use it, e.g. versus gmail_preview_message for a lighter fetch.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description repeats the read-only nature and adds return-field context, but it does not add much beyond annotations for this simple read-only profile call.

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

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

Two short sentences, front-loaded with the return value and followed by the use case. Every sentence adds information, with no filler.

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

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

For a zero-parameter read-only identity tool with rich annotations, the description names the returned fields and the operational use case. An output schema is unnecessary because the description sufficiently identifies what comes back.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain. The baseline for zero parameters 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: returns the active Gmail identity, naming key fields (emailAddress, totals, historyId). It is clearly distinct from sibling tools, though it does not explicitly contrast with the closest siblings such as gmail_get_send_as.

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

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

Gives a clear use case: confirm which account the server acts as. It does not mention exclusions or alternatives, but the context is sufficient for an agent to know when this zero-parameter profile check is appropriate.

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 trailing "Read-only." is redundant. The one sentence that earns its place is "Signature HTML is untrusted content", which flags a prompt-injection risk the annotations do not express. Beyond that, nothing about completeness of the alias set or permission requirements is disclosed.

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

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

Three short, front-loaded sentences: what it returns, the security caveat, then the safety profile. Zero filler and the most decision-relevant information comes first.

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

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

For a zero-parameter read tool with rich annotations and no output schema, the description covers the essentials, including a partial sketch of return fields (display names, signatures). Only the absence of any note on the primary-address entry or required auth scope keeps it from a 5.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the schema is empty by design. Baseline is 4; the only missing nuance is that the call returns all aliases with no filtering option.

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 ("Lists send-as aliases") and names the returned fields (display names and signatures), which lets an agent distinguish it from gmail_get_profile or gmail_list_labels. No sibling is explicitly named as an alternative, so it falls short of 5.

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

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

The description never says when to call this versus gmail_get_profile, nor does it state any prerequisite (e.g. settings scope). The usage is only inferable from the name and the word "Lists"; no exclusions or alternatives are given.

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 bar is lower; the description still adds real value beyond them by disclosing the HTML-to-Markdown conversion, the pagination behavior, and the critical prompt-injection warning that thread content is untrusted. It omits what 'summary' means relative to the tool name, which keeps it below a 5.

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

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

Three short sentences, front-loaded with the core action, and the security warning is placed last where it is most visible. 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?

No output schema exists, and the description covers the transformation, pagination, and trust posture, which is nearly everything needed to call it safely. The only gap is that the tool is named 'thread_summary' yet the description never says what makes the return a summary rather than a full thread dump.

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 four parameters are already documented in-schema; the description only gestures at pagination without adding syntax or defaults. Baseline 3 applies where 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?

Specific verb and resource ('Fetches a Gmail conversation') plus the transformation it applies ('converts HTML bodies to safe Markdown'). It doesn't name or contrast any sibling (e.g. gmail_get_message_details, gmail_get_attachment), so a 4 rather than 5.

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

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

Pagination is mentioned ('Supports pagination for long threads'), which implies the use case for part of the schema, but there is no explicit when-to-use/when-not guidance and no routing to alternatives such as gmail_search_messages or gmail_get_message_details.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the trailing "Read-only" is largely redundant. The one genuine addition is the word "identifiers," which tells the agent the payload is lightweight ID references — useful since there is no output schema — but permissions, rate limits, and ordering are unaddressed.

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

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

Two short sentences, front-loaded with the operation and scope. The trailing "Read-only." is a minor waste given the annotations already assert it, but nothing else is 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?

For a one-parameter read tool with no output schema, the description adequately covers what comes back (identifiers) and why one would call it. Missing only edge-case behavior, e.g. what an empty draft list looks like or whether results are ordered by recency.

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

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

Schema description coverage is 100% and the single max_results parameter carries its own description with default and min/max bounds. The description adds no further meaning about truncation behavior or whether a total count is surfaced, 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 ("Lists Gmail draft identifiers") and pins down the granularity of the return — IDs, not full draft bodies — which distinguishes it from gmail_get_draft and gmail_list_templates. It stops short of naming those siblings explicitly, so the differentiation is implied rather than stated.

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

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

"for human review before sending" implies a pre-send inspection workflow, which is a plausible usage context. However, it gives no explicit when-not guidance and doesn't route the agent to gmail_get_draft when full draft content is needed instead of just identifiers.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so "Read-only" in the description is largely redundant restatement. The one piece of added value is disclosing that each entry contains criteria and actions, but permissions, pagination, or volume of results are not mentioned.

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

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

Two short sentences, front-loaded with the purpose and zero padding. The trailing "Read-only." duplicates the annotations rather than adding information, costing a point.

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

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

For a parameterless, read-only listing tool with full annotation coverage, the description covers what the tool is and roughly what it returns. Only the absence of any note on result cardinality or ordering keeps it from the top score.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The parenthetical on returned fields compensates slightly for the absent output 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 ("Lists Gmail filter definitions") and even sketches the returned shape as criteria + actions, which lets an agent distinguish it from gmail_create_filter and gmail_delete_filter by name. It stops short of naming a sibling explicitly, so it doesn't earn a 5.

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

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

Usage is only implied — an agent can infer this is the inspection step before create/delete filter operations, but the description never states when to use it or when another tool is a better fit (e.g. gmail_list_labels).

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, so the 'Read-only' sentence is redundant, but the description adds real cost information: include_counts triggers extra API calls. That is a behavioral trait not present in 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?

Four short clauses, each front-loaded with the essential fact: purpose, optional enrichment with cost, safety, and sequencing. Zero filler.

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

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

A single optional boolean plus rich annotations and no output schema means little else is needed. Only the shape of returned label metadata is left implicit, which is a minor gap.

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

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

Schema coverage is 100% and the schema's own description of include_counts ('Estimate total/unread per label via filtered searches (extra API calls)') already covers both the meaning and the cost. The description largely restates it, 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 ('Lists Gmail label metadata'), clearly distinct from the many message/thread/draft siblings and from gmail_apply_labels. It stops short of describing output shape, but the operation is unambiguous.

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

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

Gives an explicit sequencing rule ('Use before gmail_apply_labels') and a conditional enrichment path via include_counts. No when-not guidance is given, but the primary use 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, and the description's 'Read-only, no I/O' merely restates them. The only added semantic content is 'built-in', which clarifies these are fixed server-side templates rather than user-created ones, but no return shape or template metadata is described despite there being no output 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?

Two short sentences with the core purpose front-loaded; nothing needs to be read twice. The second sentence is largely redundant with the annotations, which is minor waste but not harmful.

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 list tool this is close to sufficient, but with no output schema the description should say what a returned template looks like (name, id, locale, body?) and whether the list is fixed. As written, an agent knows the intent but not the payload.

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

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

The tool takes zero parameters and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline for a parameterless tool applies.

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

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

The description uses a specific verb and resource ('Lists built-in composition templates') and even gives three example template names, so the agent knows exactly what comes back. It does not, however, differentiate from the closely related sibling gmail_render_template, leaving the list-vs-render distinction implicit.

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

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

There is no statement of when to call this versus the obvious alternative gmail_render_template, nor any prerequisite or sequencing hint (e.g. 'call this first to discover valid template names'). Usage is only inferable from the tool name.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld. The description adds real context beyond them: results are thread metadata rather than full message bodies, and paging is supported via tokens. It does not mention how the extra API cost of include_from behaves, but that detail lives in 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?

Three short sentences, each earning its place, with the core purpose and the "metadata only" constraint front-loaded. 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?

With no output schema, the description carries the burden of explaining what comes back, and "thread metadata only" is vague about which fields (id, snippet, labels, date) are present. The safety profile and paging are adequately covered elsewhere, but the return-shape gap keeps this at minimum viable.

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

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

Schema description coverage is 100%, so every parameter including the Gmail query syntax example and the include_from cost note is already documented. The description adds no parameter semantics beyond echoing token-based paging, 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 ("Searches Gmail ... returns thread metadata only") and the "metadata only" qualifier implicitly separates it from message-level tools like gmail_search_messages. It stops short of naming a sibling directly, so it is clear but not maximally differentiated.

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?

"Supports page tokens to walk large result sets" gives implied usage for pagination, and "Read-only" frames safe context. But there is no explicit guidance on when to pick this over gmail_search_messages, gmail_semantic_search, or gmail_get_thread_summary.

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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false); the description adds genuine value beyond them by disclosing the concrete label side effects, reversibility, and that the action is audited with the supplied reason. It stops short of mentioning required scopes or any limits, 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 tight clauses, front-loaded with the action and its effect, then reversibility, then the audit note. Zero filler.

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

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

Behavior is well covered for a mutation tool, but with an entirely undescribed parameter set and no output schema, the agent still lacks guidance on what id accepts and what defaults apply. Adequate, with a clear gap.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it only partially does: 'message/thread' hints at the type enum and 'Audited with reason' hints at the reason field, but id format, defaults, and the 3-500 char reason constraint go unmentioned. Two of three parameters remain opaque to the agent.

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 ('Reports a message/thread as spam') and even spells out the exact label mutation (adds SPAM, removes INBOX). This clearly separates it from siblings like gmail_trash_message and gmail_unmark_spam without opening any schema.

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

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

Names the exact reversal path ('Reversible via gmail_unmark_spam'), which tells the agent when to reach for the sibling instead. It does not, however, contrast with gmail_trash_message or gmail_restore_message, so the choice among destructive-ish actions is left partly 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?

Adds context beyond the annotations: it mirrors the send path exactly so validation is faithful, and it reports the detected content_type. The read-only guarantee is restated but reinforces the readOnlyHint. It does not say how validation failures are surfaced or whether attachments/paths are checked for existence.

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

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

Three short sentences, front-loaded with the core dry-run behavior, with the sibling reference and the return hint following. 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?

There is no output schema, and the description only partially covers returns (the rendered message and content_type) without describing validation error reporting or structure. For a 9-parameter preview tool, that leaves a meaningful 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?

With 9 parameters and only 33% schema description coverage, the description must compensate but does not: to, subject, body, cc, bcc, thread_id and attachment/inline-image semantics are never explained beyond the schema's own text. The only param-adjacent content is the content_type detection, which loosely maps to is_html.

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 (validates/previews) and resource (the exact message gmail_send_message_strict would send), and explicitly contrasts with the sibling send tool. The agent can distinguish dry-run from actual send 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?

Clear implied usage: call this to check a composition before invoking gmail_send_message_strict, with the sibling named. No explicit exclusions or edge conditions (e.g. whether it should be used for every send or only HTML/complex bodies) are given.

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 idempotent, so the description's 'read-only toward Gmail' is consistent reinforcement plus added context (privacy: embeddings run locally, nothing leaves the machine; data source limited to recent inbox threads). It adds meaningful non-schema behavior, though it omits duration/cost of a rebuild.

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: what it does, where data goes, and safety posture. Front-loaded with the action; nothing 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 zero-param, idempotent, local operation with no output schema, the description covers action, data scope, privacy, and Gmail-side safety. Minor gap: no guidance on when to trigger a rebuild or expected latency.

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 baseline is 4. The description usefully clarifies that the corpus is 'recent inbox threads' since no parameter controls scope — that is exactly the kind of info a param-less tool needs.

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 (rebuilds) + resource (local semantic search index) + scope (recent inbox threads). Clearly distinguishable from siblings like gmail_semantic_search (which queries) and gmail_search_messages (Gmail-side 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?

Implies usage context ('from recent inbox threads') but never states when to run this versus using gmail_semantic_search, nor how often/when a rebuild is warranted. No sibling is named. Usage is inferable but not guided.

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, closed-world, so the safety profile is covered. The description adds genuinely new context beyond that: 'returns subject/body' discloses the shape of the result despite no output schema, and 'no I/O' signals it performs no Gmail API call or side effect. It does not mention behavior for unknown template names or missing variables, which keeps it from a 5.

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

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

Three short sentences, all front-loaded with the core mechanic first and the return value and safety note after. No filler; 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 two-parameter transform tool with a nested object, the description is close to sufficient: it names the input (template + placeholders) and the output (subject/body) even without an output schema. Minor gaps remain around error handling for missing templates or unused variables, but nothing blocks 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% and both parameters are documented in-schema (name sourced from gmail_list_templates, variables with an example). The description's mention of {{variable}} placeholders lightly reinforces how the variables object maps to the template but adds little beyond the schema's own wording.

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

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

States a specific verb and resource ('renders a built-in template substituting {{variable}} placeholders') and adds the outcome ('returns subject/body ready for draft/send tools'), which separates it from gmail_create_draft, gmail_send_message_strict, and gmail_list_templates. An agent can tell this is a pure transform tool, not a mailbox writer.

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?

'Returns subject/body ready for draft/send tools' gives clear workflow context: render here, then hand the result to a draft or send tool. It stops short of naming the exact sibling or stating when-not to use it (e.g., listing templates first via gmail_list_templates), so it is clear but not exhaustive.

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

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

Annotations declare non-readOnly, non-destructive, non-idempotent, open-world, but the description adds the crucial behavior that it never sends and the output is a reviewable draft, plus an audit note. It does not mention required scopes/auth or whether repeated calls create duplicate drafts, which matters given idempotentHint=false.

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, front-loaded sentences with zero filler; the quoting behavior, the never-sends guarantee, and the audit note each earn their place.

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

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

For a 6-parameter mutation tool with no output schema, the description covers purpose and safety well but says nothing about the return value (draft ID?) or thread placement, forcing the agent to infer result handling. Adequate but with clear 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 description coverage is only 33% — message_id and comment are documented, but to, cc, bcc, and is_html are bare in the schema, and the description does not clarify them. It also never explains how is_html interacts with the quoted '> ' text, leaving a key ambiguity unresolved.

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

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

States a specific verb and resource (creates a reply draft) plus the defining behavior (quoting the original with attribution and '> ' lines), which cleanly separates it from gmail_create_draft and gmail_send_message_strict in the sibling list.

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

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

'Never sends; review the draft' sets the usage context clearly and implies the follow-up path to gmail_send_draft. It does not explicitly name alternatives such as gmail_create_draft or state when-not to use this tool, so it stops short of the top score.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, and openWorld=true, so the safety profile is covered. The description adds the useful detail that this is an untrash (a reversal, hence idempotent and non-destructive), but it does not say what happens on error (e.g., item not in Trash) or where labels/state are restored to.

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

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

A single front-loaded sentence with no filler; the verb, resource, and source location appear immediately.

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, non-destructive, idempotent operation with rich annotations and no output schema, the description is nearly complete. The remaining gap is error/edge-case behavior and id-type coupling, which are minor here.

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

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

Schema description coverage is 0%, so the description carries the burden. 'message or thread from Trash' hints at the `type` enum and the corresponding meaning of `id`, but it never states that `id` must be a message ID when type=message and a thread ID when type=thread.

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

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

States a specific verb (restores), resource (Gmail message or thread), and scope (from Trash), plus the underlying mechanism (untrash). It is effectively the inverse of gmail_trash_message, though it never names that 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 implied by the domain: use it to bring back something that was trashed. There is no explicit when-to-use/when-not, no mention of what to do if the item is not in Trash, and no guidance on choosing between restoring a message vs a whole thread.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so 'Read-only' in the description is redundant. The one piece of added context is the return shape ('message IDs with snippet and labels'), which is useful but thin, and nothing is said about pagination behavior despite a page_token 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 short sentences with zero filler, and the level distinction is front-loaded before the return-shape detail. Nothing needs trimming.

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 search tool with no output schema, the brief return description helps, but two of three parameters are undocumented and pagination via page_token is never explained. An agent could call it on the required query alone, but would not know how to page or cap results correctly.

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

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

Schema description coverage is only 33%, so the description carries most of the burden, yet it explains no parameters at all. The query syntax is conveyed only by the schema's inline example, and page_token and max_results (with its 1-50 cap and default 10) are undocumented in both the description and 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 ('Searches Gmail at message level') and immediately contrasts it with the sibling that operates at thread level, gmail_list_threads. An agent can distinguish this from gmail_list_threads without opening either schema.

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

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

Names the alternative gmail_list_threads explicitly and gives the condition that selects this tool ('message level vs thread level'). However, it does not address other plausible alternatives in the sibling set such as gmail_semantic_search or gmail_get_message_details, leaving the boundary partially inferred.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so 'Read-only' in the description earns no credit. It does add genuine context beyond annotations: the first-run index build causes latency, embeddings are computed locally (a privacy/data-residency signal), and multilingual coverage including Spanish is disclosed.

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

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

Three short sentences, zero waste, with the core purpose front-loaded and the operational caveat immediately after. Every sentence carries distinct information.

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

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

For a two-parameter search with rich annotations and no output schema, this covers purpose, cost, and language scope adequately. Remaining gaps are how index staleness is handled and that gmail_reindex_semantic exists to rebuild it, plus no hint about result ordering.

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 with natural-language guidance and bounds. The description adds nothing beyond the schema about query format, ranking behavior, or how max_results interacts with relevance ordering, 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 ('Searches inbox threads') plus the distinguishing mechanism ('by meaning using local embeddings'), which implicitly separates it from the keyword-based gmail_search_messages sibling. It stops short of naming that sibling explicitly, so the differentiation is inferential rather than stated.

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

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

The description implies when the tool is appropriate ('by meaning') and warns that the first run builds the index and is slow, which is useful operational context. However, it never says when to prefer it over gmail_search_messages or when to call the sibling gmail_reindex_semantic, so usage is only implied.

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

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

Annotations already declare non-read-only, open-world, non-idempotent, non-destructive. The description adds two facts annotations can't convey: the draft must have been human-reviewed, and the action is audited — meaningful for an agent deciding whether to log or warn. It doesn't cover failure modes or irreversibility of the send.

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

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

Three short sentences, zero padding, and the core action plus the routing rule are front-loaded in the first two sentences.

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

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

For a single-parameter send tool with full annotation and schema coverage, this is nearly complete — safety, scope, and routing are all addressed. Only error behavior and post-send side effects are left implicit.

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 schema description coverage is 100% ('Gmail draft ID to send'), so the schema already carries the semantics. The description adds only the qualifier 'existing', which is implied by the schema; baseline 3 applies.

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

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

Specific verb + resource: 'Sends an existing Gmail draft'. It also scopes the object ('reviewed by a human') and contrasts with direct send, so an agent can distinguish it from gmail_send_message_strict and gmail_create_draft without opening schemas.

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?

'Prefer this over direct send when a draft already exists' gives an explicit selection rule against the closest alternative. It stops short of stating when-not to use it (e.g. draft not yet reviewed, draft missing) or what happens on an invalid draft_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 declare readOnly=false, openWorld=true and idempotent=false; the description usefully adds the confirm_send=true safety gate and the HTML rendering behavior (multipart/alternative with plain fallback). It does not mention irreversibility, quota/rate limits, or auth scope, but with annotations present the bar is lower.

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 purpose, then the hard requirement, then the HTML behavior, then the workflow preference. No filler or repetition.

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

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

For a 10-parameter, non-idempotent, outbound-email mutation with no output schema, the description omits what the call returns (message id/thread id) and the semantics of thread_id and attachments. It covers the safety gate but not enough of the call/response contract.

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

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

Schema coverage is only 30% across 10 parameters, so the description needs to compensate and largely does not. It restates confirm_send and is_html, which the schema already documents, while leaving thread_id (does it thread the message or create a new one?), to/cc/bcc constraints, and body format entirely unexplained.

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 ("Directly sends a Gmail message") and adds a differentiator: "This is the only direct-send tool." That implicitly separates it from gmail_create_draft and gmail_send_draft, though the siblings are not named 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?

"Draft-first is preferred" signals when not to use this tool and routes toward the draft workflow, and the confirm_send=true gate is stated up front. It stops short of naming the alternative tool or spelling out the conditions (e.g., irreversible send, no undo) that should decide the choice.

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 and idempotent safety, and the description adds genuinely new context: it is a local heuristic with no extra scopes required, and it never auto-sends to suggested addresses. That last caveat closes a real safety question an agent might have before inserting a suggestion into a draft.

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

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

Four short clauses, front-loaded with what the tool returns and how it ranks. No filler and no repetition of the annotations.

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 only two parameters, no output schema and a terse input spec, the description should say what actually comes back (bare addresses? ranked pairs?) and how recency is bounded. "Frequency-ranked From headers" hints at the shape but leaves the return format underspecified.

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

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

Schema coverage is only 50% — query is documented in-schema but max_results has no description beyond its bounds. The description clarifies that the query matches against recent-thread senders, which adds some semantic meaning, but it says nothing about how max_results limits the ranked output.

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

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

The description gives a specific verb and resource ("Suggests recipient addresses from recent threads") plus the mechanism (frequency-ranked From headers), which distinguishes it from a plain address-book lookup. It stops short of naming the closest sibling (contacts_search) as the alternative for directory-based lookup.

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 phrasing implies a compose-time use case, but the description never states when to prefer this over contacts_search or gmail_search_messages. There are no explicit exclusions or routing guidance, so the agent has to infer the entry point.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds meaningful context beyond that: the operation is a soft delete into Trash, not permanent removal, which is important because 'destructive' could otherwise suggest irreversible deletion.

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 tightly written sentences, front-loaded with the core action and ending with an important safety clarification. No wasted text.

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 mutation tool with rich annotations and no output schema, the description covers the essential behavior and reversibility. It is slightly incomplete on parameter semantics and sibling routing, but an agent can still call it correctly given 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 only 33%: the 'reason' parameter is documented, but 'id' has no description and 'type' has only an enum/default. The tool description does not explain the id format, the message-vs-thread distinction, or the mandatory nature of reason, so it does not compensate for the schema gap.

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 (soft-deletes/moves to Trash) and resource (Gmail message or thread), and rules out permanent deletion. It is clear, but it does not explicitly distinguish itself from sibling batch operations such as gmail_batch_trash or restore flows.

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

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

The description implies this is the deletion path by noting permanent delete is unavailable, but it gives no explicit when-to-use guidance, no alternatives for bulk operations, and no mention of restore behavior.

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, so the safety profile is covered. The description adds 'Audited', a genuinely behavioral detail not in annotations (the action is logged), but says nothing about permission requirements, reversibility, or whether unmarking spam affects message placement/inbox restoration.

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

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

Two short fragments, front-loaded with the core effect and zero padding. It is terse but not wasteful; slightly more could be said without hurting structure.

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

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

No output schema, 0% schema coverage, and an id/type pairing whose semantics are undefined — the description leaves the agent guessing about thread vs message targeting and about what happens to the message after unmarking. For a mutation tool this is a notable gap.

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

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

Schema description coverage is 0% for two parameters, and the description adds no parameter meaning at all. Critically, it never explains that 'id' is a message id by default but a thread id when type='thread' — a distinction the bare enum cannot convey.

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

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

States a specific verb and resource: 'Removes the SPAM label', plus the parenthetical '(not-spam)' clarifies the effect. An agent can tell this is the inverse of gmail_mark_spam from the name and description, though the description never references siblings 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?

No indication of when to use this versus gmail_mark_spam, gmail_restore_message, or label-modification tools like gmail_batch_modify_labels. The agent must infer the trigger condition (a message was mislabeled as spam) entirely on its own.

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/destructiveHint, so the safety profile is covered; 'Read-only' merely restates it. The valuable addition is the TZID caveat: it warns that times are returned raw and that start_raw must be interpreted in the named zone, which prevents a real misinterpretation bug. Slightly less than 5 because it doesn't mention scan cost or result limits.

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

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

Two tight sentences with zero filler. The core capability is front-loaded, and the timezone caveat follows immediately after as the most actionable detail.

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

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

No output schema exists, so the description should hint at return shape; naming start_raw does that partially, which is a solid touch. It still leaves open what else a result contains (event title, sender, attachment reference) and how results are ordered or truncated, so it is not fully complete.

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

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

Schema description coverage is 100% with ranges and defaults already documented for both parameters. The description conveys the general notion of a look-ahead window but adds no syntax or behavioral detail (e.g. how days_ahead interacts with max_threads truncation) 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?

Specific verb + resource: 'Lists upcoming calendar events found in recent email invites (.ics)'. This clearly distinguishes it from siblings like gmail_get_meeting_notes or gmail_search_messages, which search message content rather than extract event data.

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 resource description (scanning recent invites for upcoming events), but there is no explicit statement of when to prefer this over e.g. gmail_get_meeting_notes or gmail_search_messages, nor any exclusion or prerequisite guidance.

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

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

Annotations already declare non-readonly, non-idempotent, non-destructive, open-world, so the safety profile is carried structurally. The description adds two genuinely new facts — that the operation is a full replacement and that it is 'Audited' — but does not explain the audit implication, permission/scope requirements, or what happens to fields omitted from the call.

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 verb and resource, with no filler. 'Audited.' is a bare assertion that earns its place only weakly since it is never explained.

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

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

For a 9-parameter mutation tool with near-zero schema coverage and no output schema, the description is thin: it never states error behavior (e.g. invalid draft_id), whether draft_id/thread_id must match, or how HTML vs plain body interacts with attachments. It is adequate to start a call but not to call it confidently.

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

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

Schema description coverage is only 11% (just the attachments max-5 note), so the description must compensate. It names recipients, subject, body, attachments and is_html but says nothing about cc, bcc, thread_id, or that draft_id identifies the target — leaving over a third of the nine parameters undocumented anywhere.

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

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

The description gives a specific verb plus resource ('Replaces a Gmail draft') and enumerates the replaceable fields, which is enough to tell it apart from creation/send siblings. It does not explicitly contrast itself with gmail_create_draft or gmail_get_draft, so differentiation relies on the agent's inference.

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

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

No when-to-use or when-not guidance is given; the agent is not told to prefer gmail_create_draft for new drafts or gmail_send_draft to dispatch one. The word 'Replaces' implies full overwrite but the consequence (existing recipients/subject/body are discarded rather than merged) is left to be inferred.

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

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

Annotations cover the safety profile (non-read-only, non-destructive, non-idempotent), and the description adds genuinely new traits: ownership/permission requirement on the Pub/Sub topic, the fact that operations are audited, and that watches expire and must be renewed. It stops short of stating the expiration window or whether re-calling replaces an existing watch (relevant given idempotentHint=false).

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 terse sentences, front-loaded with the what/where, followed by prerequisites and lifecycle advice. No sentence is padding; 'Audited.' is terse but carries real 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?

Adequate for a two-parameter mutation with annotations covering safety, but it omits the expiration duration, what the call returns (expiration/historyId), and re-invocation behavior. With no output schema, the description should hint at the returned watch state for an agent to manage renewal.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the projects/PROJECT/topics/TOPIC format. The description reinforces that topic_name is required and must be owned, but says nothing about label_ids (the INBOX-default scope filter), so it adds only marginal value.

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 ('Starts') and resource ('Gmail push notifications to a Cloud Pub/Sub topic'), and even cites the underlying API method (users.watch). It implicitly contrasts with the sibling gmail_watch_stop but never names it explicitly, so differentiation relies on the agent inferring from 'Starts'.

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?

'Requires a topicName you own' and 'Renew before expiration' give clear prerequisites and lifecycle context for when to call it. It does not explicitly name gmail_watch_stop as the counterpart for teardown or state what happens if a watch already exists.

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 'Audited' note adds real context beyond the annotations, which already declare non-readOnly, idempotent, non-destructive, closed-world behavior. However, it omits the practical behavior an agent would want: whether an active gmail_watch_start is a prerequisite, whether the stop is immediate, and whether re-starting afterward requires new credentials.

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

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

Two short clauses, purpose front-loaded, with the API method and audit note appended efficiently. The 'Audited.' fragment is terse but carries information rather than padding.

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

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

For a one-parameter, annotation-covered teardown tool this is close to sufficient, but it misses the relationship to gmail_watch_start (prerequisite/state) and says nothing about the optional reason parameter, which is the only input the agent can supply.

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

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

The schema has 0% description coverage on the single 'reason' parameter, and the description never mentions it, so an agent gets no semantic guidance from either source (only a default value and a 3-500 char length bound). With low coverage the description is expected to compensate and does not.

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 ('Stops Gmail push notifications') and anchors it to the underlying API method (users.stop), which leaves no ambiguity about what is being terminated. It is implicitly the inverse of the sibling gmail_watch_start, though that sibling is never named.

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 by the tool name paired with gmail_watch_start; the description never says when to call it (e.g. before decommissioning a watch, or to silence notifications during maintenance) or what happens if no watch is active. No alternatives or exclusions are given.

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