get-message

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

With no annotations, the description carries full burden and does so thoroughly. It discloses return contents (subject, body, rfcMessageId), the effect of preferHtml, and a significant behavioral trait: timeouts when scanning large folders, plus the mitigation strategy. This goes well beyond what schema or annotations provide.

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 description is well-structured into labeled sections (Use when, Returns, Tip, Do not use when). Every sentence earns its place; it is informative without being verbose. The front-loaded use case makes it easy to scan.

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 4-param tool with no annotations but with output schema, the description is complete: it covers purpose, usage context, return values, failure modes, and alternatives. The tip about large folders and the rfcMessageId for dedup/threading show deep contextual understanding.

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 75% (3 of 4 params have descriptions). The description adds value by explaining why to pass mailbox+account ('required for reliable reads of large folders'), which goes beyond the schema descriptions. For the 'id' param, it restates the pattern (numeric or imap) but doesn't add new semantics, hence not a 5.

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 clearly states the tool's function: 'reading the full body of one message whose id you already have'. It specifies the resource (message) and the action (read/get full body), and explicitly distinguishes from siblings via 'Do not use when: you don't yet have an id (use search-messages or list-messages first), or you want the whole conversation (use get-thread)'.

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?

Excellent guidance with explicit 'Use when', 'Do not use when', and a 'Tip' section. It tells the agent exactly when to invoke this tool vs alternatives (search-messages, list-messages, get-thread), and provides a performance tip about supplying mailbox+account for large folders like 'Sent Items' to avoid timeouts.

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