search_emails

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

No annotations are provided, so the description carries the full burden. It discloses key behaviors: returns most recent first, includes specific fields, supports date range with YYYY-MM-DD format, and describes the effect of raw_criteria (ignores other filters). It also clarifies that substring filters are case-insensitive. This is transparent enough for an agent to understand what it does and how it behaves.

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 well-structured. It has three clear sentences: first states purpose and return fields, second covers date format and raw_criteria override, third explains filter semantics. No fluff, and the most important information (what it does, what it returns) is front-loaded.

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 (12 parameters, no required params, no output schema), the description covers key aspects: search scope, return fields, behavior modifiers (raw_criteria, date range), and filter types. It doesn't detail pagination or how limit works, but that's partially in the schema. The output schema is absent, so return details are partially covered. It's adequate for selecting and invoking the tool, though a bit more might be expected for such a parameter-rich tool.

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?

With 0% schema description coverage, the description must compensate for understanding parameters. It explains the format for since/before, the function of raw_criteria (overrides other filters), and the nature of sender/to/subject/text as substring filters. It omits details on limit (default 20) and larger_than_kb, but the schema provides defaults. The description adds value beyond the schema for date and raw_criteria parameters.

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 purpose: searching emails in a folder. It mentions the resource (emails in a folder) and the action (search), along with key return fields (UID, sender, subject, date, flags). It distinguishes itself from siblings like read_email and list_folders by focusing on search behavior.

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 on how to use the tool: returns most recent first, supports date range, substring filters, and raw_criteria for advanced IMAP search. It doesn't explicitly state when not to use it or list alternative tools, but the sibling list is available. However, it gives enough guidance for typical search queries.

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