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

Annotations already declare non-readOnly, non-idempotent and non-destructive, but the description adds concrete consequence ("each call creates a new draft, so retries create duplicates"), confirms it never sends, and discloses the return shape {id,message:{id,threadId,labelIds}} that no output schema provides. Value beyond annotations is real but partially overlaps the idempotency hint.

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

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

Dense, front-loaded prose with no filler: creation, non-send guarantee, return shape, downstream handoff, retry caveat, and reply recipe in sequence. Every sentence carries operational information.

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

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

For an 8-param mutation tool with no output schema, the description compensates by naming the return fields, the reply workflow, and the duplicate-on-retry hazard. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds genuine semantics: account is the sender, and threadId/inReplyTo are reply-scoped values sourced from get_message, plus the "Re:" subject convention—guidance the schema does not supply.

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

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

States a specific verb+resource ("Create a plain-text draft") and immediately distinguishes it from its closest sibling with "never sends," which separates it from send_draft. Scope (plain-text, selected account) is 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?

Gives explicit routing and sequencing: pass id to send_draft only after the user asks to send, and for replies set threadId/inReplyTo from get_message while keeping the subject. Names the alternative tools and the condition that selects them.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open world), so the bar is lower. The description adds two things annotations cannot: a 5 MB size ceiling and an explicit prompt-injection warning that returned content is untrusted data and never instructions. The return encoding/pagination behavior is not described, but the security-relevant context is the more valuable disclosure here.

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

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

Two sentences, no filler. The action and size limit come first, and the untrusted-content warning is placed last as a distinct safety caveat. 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?

For a 3-parameter, no-output-schema tool the description covers purpose, provenance of the key parameter, and a hard limit. It omits what the agent actually receives (raw bytes vs. base64 vs. a reference) and what happens when the 5 MB limit is exceeded, which are the only meaningful remaining gaps.

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

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

Schema description coverage is 100%; each of account, messageId, and partId is already documented in the schema, including the partId format example. The description reinforces partId provenance but adds no syntax or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource (download one attachment), identifies the exact source of the required partId (get_message or get_thread), and adds a concrete size boundary. It is plainly distinguishable from all siblings, none of which fetch attachment bodies.

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

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

It tells the agent where partId comes from, which implies the correct call sequence (fetch message/thread first, then this tool). It does not state exclusions or what to do if the attachment exceeds 5 MB, so it stops short of full when/when-not guidance, but for a tool with no competing sibling the routing 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?

Goes well beyond the readOnly/idempotent annotations: body decoding preference (plain text over HTML), a hard 60,000-character cap with a bodyTruncated marker, partIds handed off to get_attachment, and a prompt-injection warning that email content is untrusted data. These are non-obvious behavioral traits an agent must know before calling.

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

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

Two dense sentences, front-loaded with the core behavior and the routing alternative before the security caveat. Every clause — truncation limit, decode preference, partId linkage, untrusted-data warning — earns its place 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?

Although no output schema exists, the description fully characterizes the return payload (ids, headers, body with truncation flag, snippet, attachment metadata). Combined with annotations covering the safety profile, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 100% and both parameters are documented there (account alias source, messageId pattern/provenance), so the schema carries the parameter burden. The description adds no syntax or format detail beyond what the schema already states, which is the baseline-3 case.

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 ('Read one message') and enumerates exactly what is returned: ids, headers, decoded body, snippet, attachment metadata with partIds. It explicitly distinguishes itself from the sibling get_thread ('for a whole conversation'), so an agent can route without opening either schema.

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

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

Gives an explicit alternative and the condition that selects it ('Use get_thread instead for a whole conversation'), and implies the messageId provenance (from search_messages, get_thread or a previous result). The agent knows when this tool is the right one versus the thread-level sibling.

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 safety (readOnly/idempotent/non-destructive), and the description adds operational limits beyond them: a 200,000-character body budget, a 100-message cap, the messagesTruncated marker for cuts, and an untrusted-content warning against prompt injection.

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 sentences, each earning its place: purpose first, then the sibling-routing rule, then limits, then the security caveat. No 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 two-param read tool with no output schema and full annotation coverage, the description supplies everything an agent needs: return shape, ordering, truncation behavior, and a prompt-injection warning.

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 only two parameters, and the schema already explains account selection and the threadId source. The description adds no syntax or format detail beyond the schema, 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 ('Read every message in a conversation') plus ordering ('oldest first') and return format ('each in the get_message format'), which cleanly distinguishes it from get_message and search_messages.

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

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

Explicitly names the alternative behavior and the condition that selects it: use this instead of repeated get_message calls when replying or summarizing. No inference 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?

Goes well beyond the read-only annotations by disclosing that remote token validity is not checked, that an enrolled account can still fail with reauth_required, and that the required account argument is ignored. These are exactly the operational caveats an agent cannot infer from the schema or 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 sentences, front-loaded with the purpose and the call-first directive, followed by the two caveats. 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?

No output schema, and the description still names what is returned; it also flags the reauth_required failure mode. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the surprising fact that the required account argument is ignored and any configured alias may be passed, resolving a potential mismatch with the schema's 'selects which mailbox to use' wording. It could have reconciled the single-value enum ('inspection') with 'any configured alias' more explicitly.

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

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

States a specific verb and resource ('List configured account aliases') and enumerates the returned fields (email addresses, local enrollment state), which clearly separates it from the message/thread/label 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?

'Call first to pick the account alias for every other tool' is an explicit sequencing instruction that tells the agent when this tool must be used and why, relative to all other tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the 'Read-only' clause mostly reinforces structured data. The description earns credit by disclosing the exact return shape {labels:[{id,name,type}]} and the coverage of both system and user labels, which the annotations do not convey.

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

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

Three tight clauses: what it returns, what it covers, and why to call it. The high-value information (return shape and the modify_message_labels linkage) is 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?

There is no output schema, so the description carries the return-value burden itself and does so precisely with the {labels:[{id,name,type}]} shape. Combined with the documented account parameter and the read-only profile, nothing needed to call it correctly is missing.

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

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

Only one parameter, fully documented in the schema (100% coverage, enum of account aliases sourced from list_accounts). The description adds nothing beyond the implicit 'in the account' scoping, so the baseline 3 is correct.

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 ('List all labels in the account'), with the response shape and the label scope (system vs user) spelled out. It is clearly distinguishable from siblings like list_accounts and search_messages, and it names modify_message_labels as the downstream consumer.

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

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

It gives an explicit reason to call it — 'to map label names to the IDs modify_message_labels needs' — which tells the agent when this tool is the right one. It also excludes one misuse ('does not create labels'), though there is no true alternative sibling to disambiguate against.

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

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

Adds substantial context beyond the annotations: it declares the return value {id,threadId,labelIds}, notes reversibility via the opposite call, and states that labels must pre-exist. The only minor tension is that 'repeating the same change is harmless' reads as idempotent while idempotentHint=false, but 'harmless' is a weaker claim than 'idempotent' and does not amount to a contradiction.

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 sentences, front-loaded with the operation and return shape, then the intent shortcuts, prerequisites, and constraints. Nothing is 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?

There is no output schema, and the description compensates by naming the returned fields. For a 4-parameter mutation tool with full annotation coverage, everything an agent needs to call it correctly is present.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining what the label vectors mean operationally and by adding the cross-array constraint ('Do not list a label in both arrays') that the schema does not encode.

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

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

States a specific verb (add/remove) and resource (labels on one message) plus the return shape. An agent can distinguish it from list_labels and get_message immediately.

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

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

Gives concrete intent mappings (remove INBOX to archive, remove UNREAD to mark read, add STARRED to star), the prerequisite that labels must exist, and where to get IDs (list_labels). No inference 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 cover safety (readOnly, idempotent, openWorld, non-destructive), so the description spends its words on non-obvious behavior instead: exact return shape, newest-first ordering, no message bodies, and the quirk that `messages` is absent (not an empty array) when nothing matches. That last detail is the kind of thing that causes agent bugs and is not derivable from any structured field.

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

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

A single dense sentence, front-loaded with the verb and search mechanism, then return shape, then the routing hint, then the empty-result edge case. No filler and no repetition of schema content.

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

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

There is no output schema, so the description carries the return-value burden and does so precisely (shape, ordering, absence semantics). Combined with a fully documented 4-parameter schema and complete annotations, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100% and every parameter (query syntax, account alias, pageToken, maxResults bounds) is already documented in the schema. The description only restates the query syntax and the id/threadId relationship, adding no format or constraint detail beyond what the schema provides, 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 (Find) plus resource (messages) and the exact matching mechanism (Gmail search syntax), which distinguishes it from get_message/get_thread that fetch content by id. An agent can separate this from every sibling without opening a schema.

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

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

It routes the agent forward explicitly: pass an id to get_message or a threadId to get_thread, which effectively says 'do not use this tool to read content.' That covers the main alternative, but it says nothing about the account-scoping choice or when a search is preferable to listing labels/accounts.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is known; the description reinforces it with 'Irreversible' and adds genuinely new operational context about not blindly retrying after an unknown write outcome. It also discloses the return payload, which the absent output schema would otherwise leave unstated. Slightly short of 5 only because it does not describe auth/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?

Three short sentences, front-loaded with the action and its result before the safety caveat and the prerequisite. Every sentence carries distinct, load-bearing information with no redundancy.

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

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

For an irreversible mutation with no output schema, the description covers action, return shape, irreversibility, call conditions, and the retry hazard. An agent has everything needed to invoke it safely, including the alternative that creates the draft.

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 account and draftId are already documented in-schema, including the caveat to use the top-level id rather than message.id. The description adds no further parameter-level meaning beyond pointing at create_draft, 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?

'Send an existing draft and return the sent message {id,threadId,labelIds}' gives a specific verb, resource, and even the return shape, so the agent knows exactly what happens. It is clearly separable from siblings like create_draft or get_message.

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

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

Explicitly states the when ('only when the user explicitly asks to send this specific draft') and the when-not ('never to retry after write_outcome_unknown without checking Gmail first'), and points to the prerequisite tool create_draft. Nothing is left to inference.

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