email_batch_mark

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

With no annotations provided, the description carries full burden for behavioral disclosure, but it only states that it marks emails 'at once' and is 'faster'. It doesn't disclose return behavior, whether marks are additive or overwrite existing states, whether partial failures occur for some emails, or the IMAP sourceFolder requirement that the schema hints at. A mutation tool with zero annotation coverage should say more about side effects and prerequisites.

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?

Two efficient sentences with no wasted words. The key distinguishing value ('much faster than individual marks') is front-loaded. However, the 'much faster' claim is unsubstantiated promotional language that could be replaced with more useful behavioral detail.

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?

This is a mutation tool with zero annotations and no output schema. Given 6 parameters with 83% undocumented in the schema, the description should cover: boolean semantics (true=set or clear?), omitted-boolean behavior (leave unchanged vs clear), sourceFolder requirements for IMAP/iCloud, and partial-failure handling. None of these are addressed. The description is adequate only for the simplest non-IMAP use case.

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 description coverage is only 17%, so the description must compensate for the 5 undocumented parameters. It mentions the three boolean mark types (read/unread, starred, flagged) which maps to read, starred, and flagged params. However, accountId, emailIds, and sourceFolder are not explained in the description, and it doesn't clarify the semantics of the booleans (e.g., is 'true' applying the mark or removing it, and what happens when a mark param is omitted). The description adds marginal value over the sparse schema but leaves gaps.

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 states a clear purpose: batch-mark emails with specific mark types (read/unread, starred, flagged). It distinguishes from single-mark sibling email_mark by emphasizing 'multiple emails at once' and 'much faster', and from email_batch_delete/email_batch_move by naming the mark action. However, it doesn't explicitly name the sibling alternative email_mark as the single-item counterpart.

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 claims speed advantage over individual marks but provides no when-to-use guidance, no exclusions, and no mention of constraints like IMAP caveats (though the sourceFolder param hints at this in schema). It doesn't distinguish when to prefer this vs email_mark for single emails beyond the speed implication, and gives no context about behavior when mixing mark types in one call.

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