gmail_search_messages

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds useful behavior beyond that: it returns only lightweight summaries with specific fields and steers the agent to gmail_get_message for full content. It does not disclose pagination or auth requirements, but those are minor given the strong annotation coverage.

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 concise and front-loaded: purpose first, return shape second, and the gmail_get_message alternative last. The final 'Returns: str: JSON list of message summaries' is slightly redundant with the earlier sentence but still adds the concrete return type and does not waste space.

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

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

For a read-only search/list tool, the description plus schema and annotations are complete. It specifies what the tool does, what results look like, what parameters exist, and when to switch to gmail_get_message. Nothing an agent needs to safely and correctly invoke this tool 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?

The description adds only the high-level phrase 'using Gmail's search syntax' and does not explain query, label_ids, or max_results. However, the schema's $defs provide thorough descriptions for all three nested parameters, so the schema carries the parameter-semantics burden. Even though the top-level coverage signal is 0%, the actual nested schema is detailed enough to invoke correctly.

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: 'Search or list Gmail messages using Gmail's search syntax.' It also clarifies the scope of results ('lightweight results') and names the sibling tool for full bodies, so an agent can distinguish it from gmail_get_message 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 says to use gmail_get_message when the full body of a specific message is needed, giving a clear alternative and a condition for choosing it. The phrase 'Search or list' also tells the agent this is the appropriate tool for both query-based search and recent-message listing.

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