search_email

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

With no annotations, the description carries the full burden. It reveals the scanning order (newest first), the iteration limits (max_items, max_results), and the local-only nature. It implies read-only behavior through the verb 'search' but does not explicitly state side effects or error handling, though these are less critical for a read operation. Overall, it provides substantial behavioral context beyond a bare statement.

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 three sentences, each earning its place: the first defines the function, the second adds essential scanning behavior, and the third clarifies the underlying API. No fluff or repetition, and the key information 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?

For a search tool with an output schema (so return format is covered), the description adequately covers the core behavior and parameter semantics. It omits minor details like default folder names or error conditions, but these are inferable from the schema. The local-only constraint is a valuable addition that the schema cannot convey, making it largely complete.

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. It explains query scope via 'subject and/or body' (mapping to search_scope), and explains max_items and max_results as iteration/result limits. It also mentions folder implicitly. It does not explicit define include_body_preview or the query parameter details, but the core semantics are covered clearly despite the schema's lack of 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 locally configured Outlook desktop email by subject and/or body, which is specific and distinguishes it from sibling tools like search_contacts. It also details the scanning behavior (newest max_items messages) and result limit, making the purpose unambiguous.

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 that this uses the local Outlook profile via COM, not cloud APIs, implying when it is appropriate (local only). It does not explicitly name alternatives or exclusions, but the resource and scope make it obvious that this is for email search, not contacts or folder management. A minor gap in explicit 'use this vs that' guidance.

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