Bulk Label Gmail Messages by Search Query

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

The description discloses operational behavior: it processes up to max_results (default 20, max 100), can both add and remove labels, and returns a count and message IDs. Annotations already indicate mutation (readOnlyHint=false) and non-destructiveness (destructiveHint=false), so the description adds context about scope and return values without contradicting 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 front-loaded with a clear one-sentence summary, followed by a well-organized Args list, query examples, return information, and usage scenarios. Each section is concise and relevant, with no redundant or unnecessary 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?

The description covers all parameters, provides usage examples, states the return value ('Count of messages updated and their IDs'), and clarifies the maximum scope. Since there is no output schema, the explicit return description is essential and provided. The tool's non-trivial behavior is thoroughly documented.

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 100% of parameters, the description significantly enriches understanding by providing query examples (e.g., 'from:sender@example.com', 'subject:invoice', 'is:unread', date ranges) and clarifying the purpose of add_label_ids and remove_label_ids. It also explains the default and maximum for max_results, going beyond the schema 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?

The description clearly states the verb ('Search' and 'apply label changes') and the resource ('Gmail messages'). It distinguishes itself from sibling tools by emphasizing bulk operation via a search query rather than targeting specific message or thread IDs, as seen in gmail_modify_message_labels and gmail_modify_thread_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 provides explicit usage examples ('Use when: "Label all emails from compliance@firm.com as Compliance"') and query syntax examples. It implies the tool is for bulk, search-based label changes, but it does not explicitly mention alternatives for single-message label changes, leaving the exclusion implicit rather than stated.

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