search_gmail_messages

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does this well by explaining pagination via page_token, the return structure (Message IDs, Thread IDs, web links), and that 'user_google_email is Required.' It also notes support for standard Gmail search operators. Missing details like rate limits or authentication are not disclosed, but for a read-only search tool the provided information is substantial.

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 well-structured with a one-sentence summary, a return overview, then a clear Args list, and a Returns section. Each sentence serves a purpose and contains no filler. The format is easy to scan and front-loads the core functionality.

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 the tool's complexity (4 parameters, output schema exists, no annotations), the description is remarkably complete. It covers the search purpose, all parameters with defaults and required status, the return format, pagination behavior, and links for manual verification. There is no significant missing context that would prevent an agent from using the 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?

Despite 0% schema description coverage, the description's Args section fully documents all four parameters. It explains that query supports standard Gmail search operators, user_google_email is required, page_size defaults to 10, and page_token should use next_page_token from a previous response. This adds meaningful detail beyond the bare schema, fully compensating for the lack of 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 tool 'Searches messages in a user's Gmail account based on a query,' which is a specific verb+resource combination. It distinguishes itself from sibling tools like get_gmail_message_content by focusing on search and returning Message IDs, Thread IDs, and web links, not content. This unambiguous purpose differentiates it well.

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 clear context for when to use the tool: to find messages by query and get IDs/links for manual verification. It implies that content retrieval is not its purpose, but it does not explicitly name alternatives or exclusions, such as suggesting get_gmail_message_content for reading full messages. The guidance is therefore clear but not exhaustive.

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