mark_read_by_search

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

The description adds significant behavioral context beyond annotations: it specifies that emails are not moved (location and short ID unchanged), explains the irreversibility of the read status change, and details the dry_run default behavior. The annotations already mark it as destructive, but the description enriches that with concrete consequences.

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 appropriately sized. It begins with a one-line summary, then provides a sibling comparison, safety warning, and a clear parameter list. Every sentence serves a purpose, and the front-loaded summary immediately conveys the core function.

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 tool's complexity (8 parameters, destructive behavior, bulk operation), the description is complete. It covers purpose, sibling differentiation, safety considerations, parameter details, dry_run default, and the fact that emails are not moved. The presence of an output schema means return values do not need to be described. All necessary 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?

With 0% schema description coverage, the description fully compensates by providing detailed explanations for all 8 parameters in an 'Args' section. It covers partial matching for from_address and subject_contains, date formats for since/until, the meaning of read, max_messages limits (default 5000, max 25000), and dry_run behavior. This adds substantial meaning that the schema alone lacks.

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's function: bulk mark emails as read/unread based on search conditions. It explicitly distinguishes itself from the sibling 'mark_messages_read' by calling itself a 'bulk version', making the purpose and differentiation very clear.

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 explicit guidance: it is the bulk version of mark_messages_read, advises to use dry_run first to preview count, and warns about the irreversibility of marking many messages as read. It includes a strong recommendation to show the target and count to the user before execution, which is a clear usage guideline.

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