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

Annotations already declare readOnlyHint=true, but the description adds a genuinely non-obvious side-effect disclosure: retrieving the message 'does not mark it as read.' That is exactly the kind of state-changing behavior an agent needs to know before calling a read tool. It stops short of covering error cases (invalid UID, nonexistent mailbox) or truncation behavior.

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?

Two tight sentences, front-loaded with the operation and payload, followed by the side-effect caveat. No filler or redundancy.

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 outline headers, body, and attachments. It is adequate for a simple single-message read, though the mailbox default and error behavior remain unexplained.

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 only 33% (only maxChars is documented), so the description must compensate; it clarifies that uid identifies the single message being fetched, but says nothing about the mailbox parameter or its 'INBOX' default. Partial compensation warrants a baseline 3.

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 ('Read one message by UID') and enumerates the returned payload (headers, plain-text body, attachment list). The singular scope plus the UID key cleanly separates it from list_messages/search_messages without needing to name them.

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?

No when-to-use or when-not-to-use guidance, and no mention of alternatives or prerequisites (e.g., that the UID must first come from list_messages or search_messages). The intended use is only inferable from the verb.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context absent from the structured fields by stating the response includes message and unread counts; it omits pagination/auth details, which is a minor gap for a no-parameter read tool.

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?

A single front-loaded sentence with no filler; the scope and return contents are stated before any detail. Every word earns 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?

For a zero-parameter, read-only tool with no output schema, the description says what is returned (mailboxes with message/unread counts), which is enough to call it correctly. Slight gap: no note on auth or empty-state behavior.

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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies no filtering arguments are accepted ('all' mailboxes) and adds nothing that would mislead about inputs.

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 (list) and resource (iCloud Mail mailboxes/folders) with scope ('all') and even summarizes returned content. It doesn't explicitly contrast with siblings, but the resource is unambiguously distinct from list_messages/search_messages/get_message.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as list_messages for enumerating message contents. Usage is only weakly implied by the narrow purpose.

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

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

Annotations only supply readOnlyHint=true; the description adds two genuinely behavioral facts beyond that: results are ordered newest-first and contain headers only (no message bodies). It stops short of noting pagination or that only the default limit is returned.

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?

Two short sentences, front-loaded with the action and scoping, and the return-content caveat placed at the end. No filler or redundancy.

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 correctly covers what comes back ('headers only') and the ordering, which is the essential information for a list tool. Missing only detail about paging or how to get full message bodies (get_message).

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 50% – 'mailbox' is documented in the schema, 'limit' is not (only its type/default/bounds). The description's 'most recent' wording loosely implies the limit's role but adds no paging or format semantics, so it neither compensates nor regresses.

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?

Specific verb ('List') plus resource ('messages'), with scope qualifiers: 'most recent', 'in a mailbox', 'newest first'. An agent can tell it apart from get_message and search_messages by the recency/listing framing, though no sibling is named explicitly.

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?

Usage is implied rather than stated – the recency-scoped phrasing suggests browsing a mailbox rather than targeted retrieval (search_messages) or fetching a single item (get_message). There is no explicit when-to-use, when-not-to-use, or named alternative.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real behavioral value beyond that: all conditions are AND-ed, only headers are returned (not bodies), and results are ordered newest first. It omits pagination behavior, though limit's maximum suggests a cap.

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 short sentences, each carrying distinct information (scope, boolean semantics, return shape), with the core purpose front-loaded. No 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?

With no output schema, the description usefully states the return shape (headers only, newest first). The remaining gap is pagination/windowing guidance given a 9-parameter search surface, but otherwise an agent has enough to call it 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 78%, with per-parameter descriptions for the match fields and defaults on limit and mailbox, so the schema does most of the work. The description contributes the AND-combination rule, which is meaningful, but adds no matching semantics (exact vs substring) or date-format guidance beyond the schema.

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 gives a specific verb and resource ("Search messages in a mailbox") and scopes the operation. It does not explicitly differentiate itself from the sibling list_messages, so the agent must infer that "search" implies filtering while "list" does not.

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?

Usage is only implied: the mention of AND-combined conditions suggests this tool is for filtered queries, but there is no statement of when to prefer it over list_messages or get_message, and no stated prerequisites or exclusions.

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