search_emails

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

Beyond the annotations (which only establish read-only, non-destructive, non-idempotent, open-world), the description discloses runtime traits the agent could not otherwise know: 1000 candidates / ~10s per call, an external 30s deadline against blocked Outlook, single-use cursors expiring in 10 minutes and lost on worker restart, and best-effort results accounting for inaccessible candidates. This is exactly the behavioral context annotations cannot carry.

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?

It is dense but front-loaded, leading with scope and ordering before filter semantics and the crucial incomplete-search warning. Nearly every sentence earns its place; the only mild cost is that several behaviors are packed into a single block, making it slightly heavy to scan.

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?

An output schema exists, so return values need not be explained, and the description covers the parts that schema cannot: pagination mechanics, cursor lifetime, coverage.exhausted semantics, and evaluation_complete accounting for inaccessible items. For a complex 11-parameter search tool, nothing an agent needs to call or interpret it correctly 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?

Schema description coverage is 0%, so the description must carry the burden, and it does for the key filters: query is a literal case-insensitive substring in subject/body/subject_body, query_in selects the field, sender matches name or SMTP address, after is inclusive and before exclusive, and both date formats are spelled out. It leaves store_id, folder_id, unread and has_attachments unspecified, with folder scope only implied by 'one folder'.

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 states a specific verb, resource and scope: 'Search one folder without recursion, newest received first,' which tells an agent exactly what operation this performs and the ordering/scope constraint. It doesn't explicitly differentiate itself from the sibling recent_emails or read_email, so the agent must infer the routing, but the core purpose is unmistakable.

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?

It gives strong operational context: filters combine with AND, how to follow next_cursor with identical filters, and the critical pitfall that zero results with coverage.exhausted=false is an unfinished search rather than a definitive negative. It doesn't name a sibling alternative or state when-not to use this tool, so it stops short of full when/when-not guidance.

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