gmail_search

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description mentions it uses Gmail search syntax, which is helpful, but it doesn't disclose what the tool returns (message list, metadata, snippets?), whether it's read-only, pagination behavior, or how max_results affects results. For a search tool, the return format and result structure are important behavioral details that are missing.

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 sentence that is concise and front-loaded with the core purpose. The example is useful and doesn't add excessive length. It earns its place by clarifying the query syntax. No wasted words, though it could add a bit more behavioral context without becoming verbose.

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 tool has an output schema, which likely describes the return structure, so the description doesn't need to explain return values. However, with no annotations and 0% schema description coverage, the description should provide more context about how the search works, what results look like, and how max_results behaves. The example query is helpful, but the description is minimal for a tool with two parameters and no annotation safety profile.

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. The description explains the 'query' parameter by giving an example of Gmail search syntax, which adds meaning beyond the schema's bare 'Query' label. However, it doesn't explain 'max_results' at all, and the schema only says 'default: 10' without further context. The description partially compensates for the query parameter but leaves max_results undocumented.

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: searching Gmail messages using Gmail's search syntax. It provides a concrete example ('from:x@y.com is:unread') that helps an agent understand the query format. However, it doesn't explicitly distinguish itself from sibling tools like gmail_get_message or gmail_get_thread, though the verb 'search' and the mention of Gmail search syntax make the purpose reasonably clear.

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 to use this tool: when you need to find messages matching a search query. It doesn't explicitly state when not to use it or mention alternatives like gmail_get_message for retrieving a specific message by ID. The example query provides some guidance on usage, but there's no explicit routing to siblings or exclusion criteria.

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