Buscar emails

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

The description goes well beyond the annotations by explaining that local Outlook text search reads only a limited batch and that the response indicates when it was not exhaustive, whereas Microsoft 365 search always runs server-side. It also explicitly states 'Não altera nada', reinforcing the readOnlyHint and adding valuable operational context.

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 and front-loads the read-only nature, then lists search dimensions, gives performance advice, and mentions the alternative tool. It is slightly longer than strictly necessary since 'Ação somente leitura' and 'Não altera nada' are somewhat redundant, but every substantive detail earns its place.

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 tool with 10 optional parameters and no output schema, the description covers the main usage dimensions, environment-dependent behavior, non-exhaustive search caveats, and follow-up actions. It does not describe the exact return format or how results are structured, which would be helpful given there is no output schema, but the essential calling context is present.

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 enriches parameter meaning by clarifying that 'texto' covers subject plus body, that folder search includes trash/deleted items, and that filters can be combined. Schema coverage is 70%, and some parameters like 'nao_lido' and 'limite' are not described anywhere, but the description adds useful semantics for the most important filtering dimensions.

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 a read-only email search tool with specific filter dimensions: sender, domain, subject, free text, date, attachment, and folder, including deleted items. It is easy to understand what the tool does, but it does not explicitly differentiate itself from the sibling 'outlook_listar_emails', relying on the tool name to carry that distinction.

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 gives clear usage context: combine filters before text search for speed, and use results for batch organization or 'outlook_ler_email' for reading a single full message. It does not explicitly say when to avoid this tool or when to prefer 'outlook_listar_emails', but it does provide a concrete alternative for follow-up actions.

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