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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds crucial behavioral context: IMAP email IDs encode folder+UID and change when moved/draft updated, and the returned ID should always be reused from the last operation. It also explains how to obtain each ID type and what not to pass, substantially enriching the agent's mental model.

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 long but well-structured into labeled sections (Email provider ID, Email reply reference, Email thread ID) and front-loaded with the core purpose. The length is justified by complex provider-specific ID semantics, though a few sentences could be tightened without losing value.

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 complexity of provider-specific ID behavior and no output schema, the description covers the most important usage context, alternatives, and dangerous inputs. It is slightly incomplete on return-value details and some parameter behavior, but for a resolution/search tool it provides enough for an agent to use it effectively.

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 schema coverage at only 13% and 8 parameters, the description must compensate, but it does not define most parameters. The text gestures at sender/recipient/subject/date mapping to to/from/any_email/after/before without naming them, and limit/cursor remain unexplained. Only account_id is documented in the schema; the description adds little per-parameter meaning.

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 opens with a specific verb and resource: 'Search/list email candidates' with the explicit purpose of mapping human references to exact email_id before operations like read/reply/trash/move. It further distinguishes itself from siblings by naming the generic IMAP fallback (email_list_folders + email_list_folder_messages), making it clear this tool is for resolution, not listing messages.

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 explicitly states when to use the tool ('before read/reply/trash/move/attachment operations'), gives a concrete alternative for generic IMAP when account-wide listing is unavailable, and lists 'Never pass' constraints. This gives an agent clear routing and exclusion guidance.

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