bulk_mark_unread

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

With no annotations provided, the description carries full responsibility for behavioral disclosure, yet it omits critical context: this is a destructive mutation affecting potentially thousands of emails, whether the operation is reversible, performance implications of 'all', or threading behavior. The agent gets no warning about the scope of impact.

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 a single, efficiently structured sentence of 9 words. It front-loads the primary action and appends the conditional filter without waste or redundancy.

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 bulk mutation tool with no output schema and no annotations, the description is minimally adequate. It covers the basic operation but lacks important contextual safeguards regarding the 'all' scope, potential volume of affected emails, or confirmation requirements that would help an agent invoke this tool safely.

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 input schema has 100% description coverage ('Mailbox' and 'Optional: only mark emails from this sender'), so the baseline is 3. The description adds minimal semantic value beyond the schema, merely noting the filtering capability without elaborating on mailbox format constraints or sender string syntax.

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 core action ('Mark all emails as unread') and scope ('all'), with the specific state change (unread) distinguishing it from sibling tools like bulk_mark_read. However, it does not explicitly differentiate this bulk operation from singular alternatives like mark_as_read.

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 mentions the optional sender filter but provides no guidance on when to use this tool versus alternatives like mark_as_read (single email) or bulk_mark_read. There are no stated prerequisites, exclusions, or conditions for proper usage.

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