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

Annotations declare idempotentHint=true and destructiveHint=false, but the description adds genuinely new behavior: the read-back verification pattern ('flags are read back off the server, so a message that could not be changed is named rather than assumed done'), the no-op semantics on unset flags, and the folder-scoping of UIDs. This goes well beyond the annotation surface.

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?

Front-loaded with the core action, then usage, caution, verification, and scoping in a logical order. Almost every sentence earns its place, though the rhetorical 'BE MORE CAREFUL WITH THIS ONE THAN WITH mark_unread' is slightly verbose and the caution is restated across two sentences.

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 batch mutation tool with no output schema, the description covers everything an agent needs: batch semantics, non-idempotent-user-expectation caution, server-side verification, and folder/UID scoping. Nothing essential to correct invocation is missing.

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 coverage is 100%, so the baseline is 3. The description still adds meaning beyond the schema with the key insight that 'a uid only means something in the folder it came from, so pass `mailbox` when the uids did not come from INBOX', which clarifies when the otherwise-invisible default matters.

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?

States a specific verb and resource ('Clear the flag/star marker on messages, restoring their unflagged state'), and explicitly differentiates itself from the sibling mark_unread by contrasting the kind of state being changed. An agent can distinguish it from flag_email, mark_read, and delete_email without opening any schema.

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?

Gives explicit when-to-use guidance ('Pass the whole set in ONE call', 'Clear the ones you were asked about and no others', 'check the set first if the request was vague') and names an alternative (mark_unread) as a comparison point. The condition for supplying `mailbox` is also spelled out.

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