Update Message

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the risk profile is covered; the description adds context beyond them — the IMAP tag-plus-move race and the instruction to split into two calls — which is genuinely non-obvious behavior. It does not state whether existing tags are preserved on a read/flag update, nor whether partial failures across bulk messageIds are atomic, leaving some mutation semantics undisclosed.

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?

Three sentences, front-loaded with the primary capability, then tag vocabulary, then the IMAP caveat — each sentence carries distinct information with no restatement of the title or schema. Nothing could be cut without losing meaning.

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 nine-parameter destructive mutation with no output schema, the description covers the operation set, target cardinality, tag vocabulary, and the key platform caveat, which is enough to call it correctly. It leaves open what the tool returns and how bulk operations report per-message failures, a modest gap given no output schema exists to answer that.

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 100%, including the moveTo/trash mutual exclusion and built-in keyword labels, so the schema already does the heavy lifting and a 3 is the correct baseline. The description adds only the framing that tags are 'Thunderbird keywords (see addTags)', which is a useful cross-reference but not additive detail about parameter behavior.

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 opens with a concrete verb ('Set') and enumerates the exact mutable attributes (read, flagged, tags) plus the two move modes, so the agent knows precisely what the tool mutates. It differentiates the singular/plural targeting (messageId vs messageIds) in the same sentence. It stops short of naming sibling tools it supersedes (e.g. deleteMessages, addTags) as explicit alternatives, which keeps it from a 5.

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?

It gives a real operational rule for when to split work: 'On IMAP, tags set in the same call as a move may not reach the moved copy: use two calls.' It also routes the agent to addTags for tag semantics. What's missing is guidance on choosing this tool over deleteMessages for removal, or what to do when neither messageId nor messageIds is supplied.

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