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

Annotations already declare readOnly, idempotent, non-destructive, and open-world. The description adds valuable behavioral context beyond that: the scope of mailboxes searched (Outlook Inbox only, Gmail All Mail) and the fact that results feed into fetch. It does not discuss result caps or pagination, keeping it short of full transparency.

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?

Dense but front-loaded: scope and return flow come first, then syntax rules, then folder caveats. Every clause conveys distinct information, though the packing of multiple rules into semicolon-separated fragments is slightly heavy.

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 single-param, no-output-schema tool with rich annotations, the description covers scope, syntax, alternatives, and result routing sufficiently. Minor gaps remain around result limits and pagination, but the essential context for correct invocation 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?

Schema coverage is 100% but the schema itself only says 'Search query'. The description meaningfully enriches the parameter's semantics by documenting syntax variants (from:, newer_than:7d, has:attachment), the plain-words fallback, and the account-prefix mechanism, which is real added meaning over the schema.

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?

States a specific verb (searches) and resource (every readable mailbox) with scope (one query) and the downstream tool (returns documents for fetch). It also distinguishes itself from the sibling search_messages by contrasting folder behavior ('search_messages with a folder looks elsewhere').

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?

Gives clear usage conditions: Gmail syntax on Gmail, plain words elsewhere, and the 'account:<id> ' prefix for a single mailbox. It points to search_messages for folder-scoped searches, implying the alternative, though it does not spell out a full when/when-not decision between the two.

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