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

Beyond the annotations, the description discloses that nothing is sent, that an empty draft is legal, and that the return value includes the draft id plus underlying message id/threadId. It also explains the safe workflow of draft-then-send. This gives the agent an accurate behavioral model for a write action.

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 four sentences, front-loaded with the core purpose and non-sending guarantee, then optionality, reply recipe, return value, and usage routing. Every sentence contributes actionable information without redundancy or fluff. The structure makes it easy for an agent to scan.

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

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

For a draft-creation tool with nine optional parameters, no output schema, and no destructive/read-only annotations, this description is complete. It covers purpose, side effects, parameter relationships, return value, required follow-up tools, and when to prefer this tool over send_message. An agent can invoke it correctly without needing additional context.

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

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

The schema already provides 100% parameter coverage with descriptions for every field, so the baseline is 3. The description adds meaningful guidance beyond the schema by clarifying that all fields are optional and by providing the reply-draft pattern for thread_id, in_reply_to, and subject. It does not elaborate on cc/bcc/body fields, but the schema already handles those adequately.

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 operation: creates a draft email in the mailbox without sending. It differentiates from related tools by explicit no-send behavior and by naming the draft id consumers (update_draft/send_draft/delete_draft). The purpose is unmistakable even without opening the schema.

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

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

The description explicitly tells the agent when to use this tool over send_message: draft first and send with send_draft after human review, prefer it for consequential mail. It also gives the exact recipe for reply drafts (thread_id, in_reply_to, subject with "Re: ") and points to get_message for the required messageId. This is clear routing guidance.

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

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

Although destructiveHint=true already signals danger, the description adds critical context: deletion is permanent, there is no undo, drafts do not go to trash, and the operation returns empty on success. This goes well beyond 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?

Two highly informative sentences, front-loaded with 'PERMANENTLY' to emphasize the key trait. Every clause earns its place: irreversibility, no-trash behavior, confirmation guidance, and return value.

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

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

For a single-parameter destructive tool with annotations and no output schema, the description provides everything needed: the action, the risk, the safety precondition, and the success response. No significant information 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?

With 100% schema description coverage and a clear draft_id description citing list_drafts or create_draft output, the schema already fully documents the parameter. The description adds no further parameter semantics, but none are needed.

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: 'PERMANENTLY deletes a draft'. It also distinguishes this tool from siblings like manage_trash by clarifying drafts skip the trash, making the tool's unique purpose 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?

It gives an explicit precondition: 'Confirm with get_draft before deleting anything the user might still want.' It also explains why alternatives like manage_trash cannot recover the draft, which helps the agent decide when and how to use the 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 readOnly, idempotent, openWorld, and non-destructive behavior. The description adds useful behavioral detail beyond that: the draft is decoded like get_message, HTML is returned only on request, and attachment metadata is included. It does not contradict the annotations.

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

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

The description is two sentences with no filler. The first sentence front-loads the core behavior and return contents, and the second sentence delivers actionable usage context and an important warning. 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 simple read-only tool with one required parameter, the description covers what the tool returns, how it behaves, when to use it, and why it matters before update_draft. The annotations cover safety and idempotency, so nothing important is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds some context by noting that include_html controls whether HTML is returned and that text body may exist, but it does not materially explain draft_id or max_body_chars beyond what the schema already states.

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

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

The description states a specific verb ('Fetches one draft'), a clear resource ('draft'), and enumerates what is returned (headers, text body, HTML on request, attachment metadata). It also distinguishes itself from get_message by explicitly modeling on it while targeting drafts, so an agent can select it without confusion.

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

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

The description provides explicit usage guidance: use it to show what send_draft would send, or to read current content before update_draft. It even warns that updates REPLACE the whole draft, giving a concrete reason to call this tool first. This clearly frames when to use it relative to its sibling 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?

Despite annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description goes far beyond them. It discloses concrete behavioral details: base64/charset decoding of bodies, truncation at max_body_chars with textTruncated/htmlTruncated flags, conditional HTML-only inclusion, and the fact that attachment content is never returned (only metadata). This transparency is essential for a tool that could otherwise surprise an agent with size limits or missing content. No contradiction with 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?

The description is dense but well-organized; it front-loads the primary action and then systematically details return components, truncation rules, and alternatives. Every sentence imparts critical information about behavior or edge cases. It is slightly long but justifiably so for a tool with decoding, truncation, and attachment-handling nuances. No filler or 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?

With no output schema, the description must carry the full burden of return-value explanation, and it does: it enumerates decoded headers, plain-text and HTML bodies, attachment metadata (not content), truncation flags, and how to obtain actual bytes via raw_request. It also covers conditional behavior (include_html) and the metadata_only shortcut. An agent has all the information needed to call this tool correctly and interpret its results.

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%, but the description adds meaningful semantics beyond the schema's terse descriptions. It clarifies that message_id is not the RFC Message-ID header, explains the effect of include_html (return HTML even when a text body exists), metadata_only skips bodies entirely, and max_body_chars truncates with a flag. This enriches the parameter meanings, though the schema definitions already cover basic intent, so the value-add is high but not exhaustive.

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

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

The description opens with a specific verb-resource pair ('Fetches one message fully decoded') and enumerates exactly what is returned (headers, bodies, attachment metadata). It clearly distinguishes itself from list_messages (listing) and get_thread (thread-level) by focusing on a single message. The level of detail leaves no ambiguity about the tool's scope.

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

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

Usage context is implied by the purpose ('Fetches one message') and the note 'To reply later, keep headers.messageId', but the description does not explicitly state when to use this tool versus siblings like get_thread, list_messages, or get_draft. No exclusions or alternative-routing conditions are given beyond the attachment-bytes mention for raw_request. The guidance is largely implicit 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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds what the query returns—profile fields—and characterizes the call as the cheapest verification of OAuth credentials, implying minimal overhead. No contradiction exists.

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

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

A single sentence that front-loads the primary behavior ('Returns the authenticated mailbox's profile') and enumerates the fields. The parenthetical examples are brief and useful, making every phrase informative without 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?

With no input parameters and a read-only annotation set, there is little an agent needs to know beyond what the tool returns; the description covers the key fields and even adds a practical use case. The absence of an output schema is mitigated by the explicit field list.

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?

There are zero parameters, so the schema is fully described by its empty object and there is nothing to document. The description's mention of the response fields is not parameter semantics but does give the agent insight into what it gets back.

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

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

The description uses the specific verb 'Returns' and identifies the resource as 'the authenticated mailbox's profile', enumerating the exact fields (emailAddress, messagesTotal, threadsTotal, historyId). This clearly differentiates it from sibling tools that operate on messages, threads, drafts, or labels.

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

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

The description explicitly states the tool is 'The cheapest way to verify that the OAuth credentials work', which tells an agent when to use it. It also mentions the emailAddress field is useful for send-to-self checks and recognizing the user's messages, providing practical context. It does not name exclusionary alternatives, but the resource is unique among siblings.

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 mark it read-only and idempotent; the description adds meaningful behavioral detail beyond that: messages are oldest-first, HTML is only returned under certain conditions, attachment metadata and truncation flags are included, and large threads can be resource-heavy. No contradiction with 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?

Every sentence earns its place: core behavior, ordering, reply workflow, and performance guidance. It is dense but well-structured and front-loaded with the most important 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?

Given there is no output schema, the description compensates by specifying what messages contain, the ordering, truncation behavior, and the reply workflow. For a read-only tool with rich annotations, this is complete enough for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds operational meaning: max_body_chars applies per message and should be lowered when only the gist is needed, and include_html only matters when a text body already exists. This goes beyond the schema's descriptions.

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 a conversation with every message' decoded like get_message. The scope (whole conversation vs. individual message) is clear and distinguishes it from the sibling get_message 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?

Provides clear practical usage context, including how to reply using the last message's IDs, and when to lower max_body_chars for large threads. It does not explicitly state when not to use this tool versus alternatives like get_message or list_threads, 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, idempotentHint, openWorldHint, and destructiveHint=false, lowering the bar. The description adds valuable behavior beyond annotations: it returns only envelope fields rather than full content, supports Gmail query syntax, and paginates with nextPageToken, which helps the agent know exactly what to expect.

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 with no filler, front-loading the core purpose and return shape before adding usage details. Every clause contributes: scope, fields returned, exclusions, query syntax, and pagination.

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 read-only listing tool, the description is complete: it covers return fields, the notable absence of subjects, the query filter mechanism, and pagination. There is no output schema, but the description supplies the key return information an agent needs, and the annotations already cover safety and idempotency.

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

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

Schema description coverage is 100%, so the schema fully documents query, page_size, and page_token. The description mentions query filtering and pagination but does not add meaning beyond what the schema already provides, 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?

States an unambiguous verb+resource ('Lists the mailbox's drafts') and specifies the return shape (draft id, message id, threadId). It explicitly differentiates from the sibling get_draft by noting it returns no subjects and pointing to that tool for full detail, so an agent can distinguish it 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?

Provides clear operational context: query filtering with Gmail syntax and pagination via page_token are described. It gives an exclusion ('no subjects — read one with get_draft'), though it does not systematically contrast with list_messages or list_threads, so it falls just short of fully explicit 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 mark this as read-only, idempotent, and non-destructive. The description adds behavioral context beyond that: it specifies that system labels are included, and that the plain list does not carry counts, while the single-label fetch does. This is useful supplemental information.

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 two sentences, front-loading the default mode and then the optional mode. No wasted words; each sentence earns its place. The structure is logical and easy to parse.

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 tool with one optional parameter and no output schema, the description is complete. It explains both call patterns, what each returns, and its role in the broader API context. There's nothing an agent needs to call it correctly that 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?

Input schema covers the single parameter at 100%, so baseline is 3. The description adds value by specifying exactly which counts are returned (messagesTotal, messagesUnread, threadsTotal, threadsUnread), which is not in the schema. This elevates the score to 4.

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 clearly states the tool's function: listing all labels or fetching a specific label with counts, distinguishing between the two modes. It also positions the tool as the vocabulary source for other tools like list_messages and modify_message, which effectively differentiates it from sibling tools.

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

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

The description explicitly states when to use each mode: 'Without label_id' for all labels, 'With label_id' for a single label with counts. It also explains that counts are only available with label_id, providing clear, actionable guidance without ambiguity.

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 readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: pagination via nextPageToken, page_size defaults and throttling, skipped deleted messages causing short pages, resultSizeEstimate being an estimate, and metadata-read costs. This goes far beyond what annotations already provide.

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

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

The description is dense but every sentence earns its place, moving from the core search behavior to return shape, filtering, pagination, edge cases, cost options, and alternatives. It is front-loaded with the most important purpose and keeps the reader oriented.

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 needs to explain return values, and it does: summary fields are listed and the bare-id alternative is described. It also covers filtering, exclusion behavior, pagination, incomplete-page edge cases, and alternative tools, making the definition complete for correct selection and 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?

Even though schema coverage is 100%, the description adds important meaning: query uses Gmail search-box operators, label_ids must all match, page_size has cost implications per metadata read, page_token comes from nextPageToken, and include_metadata=false switches to bare ids only. These are practical semantics an agent needs to invoke the tool well.

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

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

The description states a specific verb and resource: 'Searches the mailbox with Gmail query syntax' and returns per-message summaries. It clearly distinguishes itself from related tools by saying a full body should be read with get_message and a whole conversation with get_thread.

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 gives explicit when-to-use guidance: filtering via query/label_ids, excluding spam/trash unless include_spam_trash=true, and the tradeoff between include_metadata=false for cheapest results. It also routes to alternatives for body and thread retrieval, leaving no ambiguity about which sibling to pick.

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

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

The annotations already establish read-only, idempotent, and non-destructive behavior, so the description doesn't need to repeat that. It adds value beyond annotations by specifying that the snippet comes from the latest message, how pagination works, and that the same Gmail query syntax applies.

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

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

Three sentences, each with a distinct job: what the tool returns, when to choose it over list_messages, and how to filter/paginate/follow up. 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?

Given there is no output schema, the description names the per-thread return fields and points to get_thread for full content. It doesn't mention include_spam_trash or default ordering, but those are fully covered by the schema and are not essential to tool selection or 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%, so query, label_ids, page_size, page_token, and include_spam_trash are all fully documented in the schema. The description only restates filtering and pagination at a high level and adds no parameter-level meaning beyond what the schema already provides.

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

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

States a specific verb ('Searches'), a clear resource ('conversations (threads)'), and the exact return payload (id, snippet, historyId). It also distinguishes itself from list_messages by naming the different unit of work, so an agent can tell them apart 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?

Explicitly says 'Use this instead of list_messages when the unit of work is a conversation' and gives concrete examples like triaging an inbox or finding a discussion to reply into. It also points to get_thread for full conversation content and describes pagination mechanics.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses concrete consequences: delete removes the label from every message, messages themselves survive, and the operation cannot be undone. It also states that only provided fields change on update and that system labels are immutable, giving essential behavioral detail.

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

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

The description is dense but every sentence earns its place: action rules, nested-name example, visibility semantics, deletion consequences, system-label restrictions, and routing to sibling tools. It front-loads the primary verb and resource before going into conditional details.

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 three conditional action modes, five parameters, no output schema, and destructive behavior, the description covers every invocation-relevant concern: prerequisites, field-change semantics, multi-message deletion effects, irreversibility, and excluded label types. A correct call can be constructed from the description alone.

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?

Although the schema covers all five parameters, the description adds conditional semantics the schema cannot express: create requires name with optional nesting and an existing parent, update requires label_id plus at least one other field, and delete requires only label_id. It also clarifies what each visibility enum controls in the sidebar versus the message list, materially improving invocation correctness.

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 title and description name a specific resource—user labels—and three explicit operations: create, rename/update, delete. It immediately separates label management from modifying messages by directing to modify_message/modify_thread, so an agent can distinguish it from sibling tools without inspecting 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?

The description explicitly states when not to use the tool ('To apply/remove labels on mail, use modify_message or modify_thread, not this tool') and narrows scope by excluding system labels. It also provides clear action-by-action usage rules, so the agent knows exactly which sibling handles message-level label operations.

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 richly discloses behaviors beyond the annotations: trash is reversible for about 30 days before permanent deletion, target=thread acts on every message in the thread, untrash does not re-add INBOX, and the server deliberately has no permanent-delete tool. These are precisely the behavioral facts an agent needs to avoid irreversible mistakes and to reason about side effects. No contradiction with 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 sentences, all information-dense and non-redundant. The core action is front-loaded, followed by reversibility, target semantics, server policy, and the INBOX follow-up. Every sentence 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?

For a destructive-but-reversible mutation tool with no output schema, the description covers all essential calling considerations: required parameters, target modes, reversibility window, permanent deletion caveat, and the needed follow-up to restore INBOX presence. Combined with the annotations, an agent has enough context to call this tool safely and 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?

Even though schema coverage is 100%, the description adds meaningful semantics beyond the schema: it explains the 30-day retention meaning of action=trash, the thread-wide effect of target=thread, the default target=message, and the INBOX caveat for untrash. These details transform the enum values into actionable behavior.

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 exactly what the tool does: 'Moves a message or a whole thread to the Gmail trash, or restores it.' This is a specific verb+resource statement that clearly distinguishes it from sibling tools like modify_message, manage_labels, and delete_draft. The title and description are aligned and 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?

The description gives explicit context for when to use this tool: trashing/untrashing mail or threads, with no permanent-delete alternative intentionally available. It also warns that untrash does not re-add INBOX and directs the agent to follow up with modify_message archived=false when inbox restoration is needed. This is clear routing guidance beyond the schema.

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

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

The annotations mark destructiveHint=true, while the description asserts 'This never deletes anything — use manage_trash for the trash.' This categorical non-deletion claim conflicts with the machine-readable destructive hint, creating an inconsistent safety profile. The description adds useful detail (idempotence, return value), but per rubric any contradiction with annotations scores 1.

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

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

The description is front-loaded with the core action and parameter summary, then proceeds to constraints, safety, sibling routing, and return value. Every sentence adds information; there is no filler or duplication of the schema beyond what helps clarity.

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 mutating tool with no output schema, the description covers what the agent must know: parameter effects, required-change condition, idempotency, safety boundary, and the return shape (new id/labelIds). Minor omissions like explicit error behavior when no change is supplied are acceptable because the constraint is stated.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by stating the cross-parameter invariant 'At least one change is required,' explaining idempotence, and giving concrete examples of label ids (IMPORTANT, Label_123). This pushes it above baseline.

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

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

The opening line 'Changes a message's state via Gmail labels' names a specific verb and resource, and the body enumerates the exact state transitions (read, starred, archived, add/remove labels). It also distinguishes itself from the sibling manage_trash by explicitly stating 'This never deletes anything — use manage_trash for the trash.'

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

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

It gives clear invocation guidance: at least one change is required, duplicate changes are harmless, and trash-related operations should go to manage_trash. It doesn't explicitly contrast with modify_thread or other state-changing siblings, so it isn't a full when-to-use map but is sufficiently clear for most routing.

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

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

Annotations already carry the read-only/destructive/idempotent profile. The description adds useful context beyond that: the whole-thread scope, the requirement that at least one change be present, the idempotent behavior that repeated identical changes are harmless, and the return value ('thread's new id and message label state'). No contradiction with 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 compact sentences with no filler. The action and scope are front-loaded, followed by when to use it, the usage constraint, and the return behavior. 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?

Despite the lack of an output schema, the description states what is returned. Combined with the fully documented parameter schema and annotations covering safety/idempotence/destructiveness, an agent has everything needed to select and invoke the tool correctly. The only minor gap is alternative-selection wording, which is already addressed in usage guidance.

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 each parameter already has a detailed description, putting this at baseline 3. The description adds value by enumerating which fields count as 'changes' and by stating the non-schema constraint that at least one change is required. It does not add syntax details, but they are not needed given the schema's completeness.

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

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

The description names a precise action — applying the same normalized state changes as modify_message — but scoped to 'EVERY message in a conversation at once'. It lists the exact state dimensions (read/unread, starred, archived, add_label_ids/remove_label_ids), so there is no ambiguity about what the tool operates on.

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 explicitly explains when to use the tool: mark a whole conversation read or archive it in one call instead of looping over messages. It references modify_message as the baseline sibling, but stops short of explicitly saying 'use modify_message for a single message', so it lacks a full when-not statement.

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

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

Beyond annotations, it discloses that the Bearer token is added automatically, the method defaults to GET, and that DELETE is a PERMANENT delete skipping trash and requiring the full mail.google.com scope. This meaningfully extends the annotation hints without contradicting them.

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

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

The description is dense but each clause serves a purpose: purpose, examples, mechanics, and a prominent safety warning. It is front-loaded with the core escape-hatch meaning and remains scannable despite its length.

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

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

For a raw open-world API tool with no output schema, the description covers the critical invocation details: path, query strings, auth, method default, and destructive risk. It does not describe the general response shape or error behavior, but it does show one concrete return format (base64url data), which is reasonable for an escape-hatch 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?

With 100% schema coverage, the baseline is 3. The description adds value by showing exact path patterns, mentioning query strings are allowed, and clarifying the default GET method. It does not deeply elaborate on the body parameter, but the schema already covers it.

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: call any Gmail API v1 path directly. It also explicitly positions the tool as an escape hatch for requests the typed tools don't cover, using concrete endpoint examples that distinguish it from the typed sibling tools.

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

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

It gives clear when-to-use guidance: for attachment downloads, history.list, batchModify, and settings endpoints. It also gives a when-not-to-use warning: prefer manage_trash for deletes, because this bypasses guard rails and can permanently delete messages.

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?

Even though annotations already include destructiveHint=true and idempotentHint=false, the description adds meaningful detail: the side effect on the drafts list, the irreversibility of sending, the duplicate-email risk on retry, and rate-limit constraints. This goes well beyond what structured fields 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?

Four sentences, each with a distinct job: state the effect and output, instruct pre-call verification, explain no-retry and outcome checks, and list rate limits. There is no filler; the length is justified by the destructive, non-idempotent nature of the tool.

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 tool with no output schema, this description covers the returned id/threadId, the verification step, ambiguous-outcome handling, and sending limits. An agent has all the information needed to invoke it safely and detect whether it succeeded.

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

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

Schema coverage is 100% and the schema already documents 'The draft id from list_drafts or create_draft output.' The description's mention of 'existing draft' and 'verify the content with get_draft' is more about behavioral context than parameter semantics, so it meets the baseline without needing to compensate.

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

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

The description opens with a specific action and resource: 'Sends an existing draft exactly as it is stored, immediately and irreversibly.' It also states the concrete outcome (draft disappears, becomes a sent message with returned id/threadId), and the focus on 'existing draft' distinguishes it from send_message, which creates a new 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?

It gives explicit when-to-use guidance: verify with get_draft before calling and never retry after timeout or 5xx because duplicates cannot be unsent. It also names fallback checks, list_drafts and list_messages in:sent, plus daily sending limits, providing clear context for choosing between this tool and alternatives.

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

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

Beyond annotations, the description discloses irreversibility, no-retry semantics, Gmail threading prerequisites, multipart/alternative body handling, return fields, and daily sending limits. This is exactly the behavioral context needed for a destructive, non-idempotent tool.

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

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

The description is dense but every sentence carries essential information, and the layout front-loads the core send semantics before threading, retry, and rate-limit guidance. The all-caps cues ('TO REPLY IN A THREAD', 'NEVER retried') make the critical instructions easy to scan.

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

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

For a complex send operation with no output schema, the description covers inputs, output fields, failure handling, verification path, and rate limits. An agent has enough to invoke correctly and know what to do when the outcome is unclear.

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?

Although the schema already documents each parameter, the description adds cross-parameter rules: at least one recipient across to/cc/bcc, bcc-only allowed, subject or body required, and how thread_id/in_reply_to/subject must align for threading. It also clarifies references defaults to in_reply_to.

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

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

The description opens with a specific verb and resource: it sends an email from the authenticated mailbox, and adds 'immediately and irreversibly' to define the behavior precisely. This clearly distinguishes send_message from sibling draft tools and read-only tools such as list_messages 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?

It gives explicit when-to-use guidance for replies: call get_message first, then pass threadId, in_reply_to, and 'Re: ' subject. It also tells the agent not to retry after timeout or 5xx and to verify via list_messages, but it does not explicitly route users to create_draft/send_draft for non-immediate sends.

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 discloses critical behavioral traits beyond the annotations: omitted fields are dropped, the draft id remains stable, the underlying message id changes, and the response is the updated draft. The destructiveHint is consistent and the description enriches it by explaining exactly what gets replaced and what side effect occurs.

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 sentences, each carrying distinct information: the replacement semantics, the prerequisite, the state behavior, and the return value. The 'REPLACES' warning is front-loaded, and there is no filler or redundant restating of the schema.

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

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

For a 10-parameter tool with no output schema, the description is largely complete: it covers prerequisites, full-replacement semantics, reply-draft specifics, id stability, and the return value. It doesn't enumerate every parameter but the schema already does that. A brief note on error conditions or permissions would make it fully complete, but that's 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%, so the baseline is 3. The description adds semantic value by explaining that parameters represent the complete new state rather than deltas, and calls out the thread_id/in_reply_to pairing for reply drafts. This goes beyond simple parameter descriptions and prevents common misuse.

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

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

The description opens with 'REPLACES a draft's entire message', naming the specific verb and resource, and immediately clarifies the key distinguishing trait: this is not a partial edit. It clearly differentiates update_draft from siblings like create_draft and delete_draft by focusing on replacement of an existing draft's full content.

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

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

The description gives explicit procedural guidance: read current content with get_draft first, then pass the complete new state. It also states when thread_id/in_reply_to are relevant. It doesn't explicitly contrast with alternatives like create_draft or send_draft, but the get_draft prerequisite and full-replacement instruction provide clear usage context.

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