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

Goes well beyond the annotations by disclosing that nothing is sent or deleted, that archive/unarchive act at conversation level, that a single unknown or hidden id fails the whole call atomically, the 1–50 id cap with overflow returned as skipped, and the MAIL_UPDATE_REQUIRED error. These are exactly the behavioral traits an agent needs and the annotations (readOnly=false, destructive=false, idempotent=false) do not supply.

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?

Dense but front-loaded, with the core action and the usage restriction in the first sentence and constraints ordered by importance. It is a single long paragraph, so error-code details could be more scannable, but no sentence is filler.

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?

There is no output schema, and the description compensates by explaining the updated return value and its empty-when-already-in-state behavior, plus the failure codes. Only locale is left undefined, which is minor for a mutation tool whose side effects and error modes are otherwise fully described.

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?

With 0% schema description coverage the description must carry the load, and it does for two of three parameters: it defines id provenance and limits, and explains that mark_read/mark_unread only apply to received messages while archive/unarchive are conversation-scoped. The locale parameter is never mentioned, leaving one gap.

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 set (mark read/unread, archive/unarchive) on a specific resource (messages in the authenticated business mailbox), and scopes it as housekeeping rather than sending. This clearly separates it from send_business_email and from the read-only list_business_emails/get_business_email siblings.

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?

Explicitly says to use it 'only when the user asks,' names the two sibling tools that must supply the ids, and states the MAIL_UPDATE_REQUIRED prerequisite. Both the when and the when-not/where-ids-come-from are spelled out.

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