batch-mark-as-unread

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

Since no annotations are provided, the description carries full responsibility. It discloses the return value ('counts of how many were marked unread and how many failed'), the failure/refusal behavior for ambiguous ids ('an id that matches in several mailboxes is refused, not guessed'), and the importance of sourceMailbox/sourceAccount for pinning ids. This goes beyond the schema and provides critical runtime behavior.

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 compact and well-organized, with clear 'Use when', 'Returns', 'Do not use when', and 'Pass' sections. Every sentence adds either usage guidance, a return detail, or parameter semantics, with no filler. It is front-loaded and scannable.

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 a batch tool with 3 parameters and an output schema, the description is complete. It explains when to use, what to expect in the return, how to obtain inputs, and how to disambiguate ids. It even handles edge cases like ambiguous mailboxes. The presence of an output schema reduces the need to describe return structure, but the description still provides the essential counts summary.

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 schema description coverage is 67%, but the description compensates by explaining the ids parameter's numeric/IMAP format and the purpose of sourceAccount/sourceMailbox. It clarifies that sourceAccount alone pins nothing and that sourceMailbox must be paired with it, and that imap ids ignore the mailbox scope. This adds meaningful semantic context beyond 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?

The description clearly states the verb and resource: 'marking multiple messages (1–100 ids) as unread in one call.' It also distinguishes from siblings by explicitly mentioning when to use mark-as-unread for single messages and batch-mark-as-read for the read counterpart. This is a specific, unambiguous purpose.

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 begins with an explicit 'Use when' condition and provides a 'Do not use when' clause with direct references to alternative tools. It also gives a prerequisite step ('Get the ids from search-messages or list-messages first'), which is valuable guidance for correct usage.

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