search_emails

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

With no annotations, the description carries the full burden. It discloses that the tool consolidates multiple search types, supports pagination and date filtering, includes a warning about body text search being slower, and mentions output format options. It does not mention idempotency or side effects (likely read-only), but overall is transparent.

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 concise introductory sentence followed by a detailed parameter list. It is front-loaded with key capabilities. However, it is relatively lengthy due to the number of parameters, but every sentence adds value. Could be slightly more compact, but still effective.

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 high parameter count (17) and no annotations, the description covers all necessary context: parameter behavior, performance trade-offs, output format options, and pagination. The presence of an output schema likely handles return value documentation. The description is complete and leaves no major gaps.

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 significant value beyond the bare input schema (which has no descriptions). Each parameter is explained with usage notes, defaults, and warnings (e.g., account: 'searches ALL accounts (slower)', body_text: 'significantly slower'). It clarifies optionality and behavior, fully compensating for the 0% schema coverage.

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 identifies the tool as a unified email search with JSON output, pagination, and real date filtering. It distinguishes itself from sibling tools like list_inbox_emails (which likely lists without search) and get_email_thread (which retrieves a specific thread). The verb 'search' is implied and the resource 'emails' is specified.

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 explains when to use this tool: for searching emails with filters like subject, sender, body text, etc. It provides performance warnings for body search and search across all accounts. However, it does not explicitly state when not to use it or list alternatives like list_inbox_emails for simple listing.

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