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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, yet the description still adds substantial behavior: a four-state outcome taxonomy, retry permissibility per state, and a specific failureCode that signals a permanent per-message gap. That is exactly the kind of information (what the caller can and cannot retry) annotations cannot express.

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 operative constraint is front-loaded in the first sentence and the remaining sentences are spent on outcome semantics rather than filler; nothing is redundant. It is dense as a single run-on block, so the status definitions would scan faster as a short list, but no sentence fails to earn its place.

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?

With no output schema, the description carries the return-value burden and does so well by enumerating statuses and the one failureCode that changes caller behavior. It is slightly incomplete on what "linkage metadata" actually contains and on the role of accountId, but an agent has enough to call it and interpret the result correctly.

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 50% and the description says nothing about either parameter, so it adds no meaning on its own. The messageId schema entry is genuinely rich (opaque, never reconstruct, use the replacement ID after archive/move), but accountId is undocumented in both schema and description, leaving the compensating work half done.

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?

"Read one exact message from the durable cache without contacting a provider or queuing a refresh" gives a specific verb (read), a single-resource scope (one exact message), and an explicit operational boundary (cache-only, no provider call), which is precisely what separates it from get_email or the thread-level 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?

It gives strong decision guidance on the outcome side: which statuses are retryable (body_pending, not_cached) and which is a durable terminal gap that must not be retried (unsupported + message_body_oversize), including what to do instead. It never names the sibling to use when a provider fetch or thread read is actually wanted, so the alternative-selection guidance is implied rather than stated.

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