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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds meaningful context with 'permitted' (implying permission scoping) and 'stable IDs' (implying persistent identity across calls), which is beyond the annotations, but it does not discuss ordering, empty results, or account states.

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 compact sentence with the resource and the key output characteristic front-loaded. No filler, no 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?

For a no-parameter list tool with annotations covering the safety profile and an output schema covering the return shape, this description is nearly sufficient. It could add a note on ordering or on what 'permitted' means in practice, but nothing an agent needs to invoke it correctly is missing.

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 per the rubric the baseline is 4. With 100% schema coverage and no inputs to explain, there is nothing further the description could add here.

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 ('List') and resource ('permitted Apple Mail accounts') plus a useful output detail ('stable IDs'), which cleanly separates it from siblings like list_mailboxes and search_messages by resource type. It stops short of explicitly naming a sibling, but the resource is unambiguous.

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?

There is no guidance on when to call this versus alternatives such as list_mailboxes, nor any stated prerequisites or context. The sentence only describes what the tool returns, leaving the agent to infer usage.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuine behavioral fact — that results are nested/recursive arrays of names — but says nothing about auth requirements, sorting, or coverage limits.

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 padding. It earns its place, though it is terse enough that it sacrifices clarity for brevity.

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?

An output schema exists, so return-value explanation is not required, and annotations cover the read-only safety profile. What remains missing is any account_id semantics and any routing guidance among the sibling list/search tools, leaving the definition minimally adequate.

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 0% and there is one required parameter, account_id, which the description never explains (format, where it comes from, whether it can be omitted). With no schema-level documentation to fall back on, the description fails to compensate for the coverage 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?

The description states a clear verb+resource ('List account mailbox paths') and adds scope ('including nested mailboxes'). It is reasonably distinguishable from list_accounts and read_message, though the boundary with the sibling search_inboxes is left implicit rather than stated.

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?

There is no guidance on when to call this versus the alternatives — no mention of search_inboxes, search_messages, or any precondition. Usage must be inferred entirely from the name.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral trait — that the body is length-bounded — but never says what the bound truncates, what happens to the remainder, or how the caller detects truncation. With annotations doing the heavy lifting, the added context is modest.

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 that identifies the resource, the identifier, the scope and the one notable behavioral constraint with no filler. It is efficient, though the terseness is partly what leaves parameter and truncation details unexplained.

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, so the description carries the burden of describing what comes back, and it does not: no mention of headers, attachment handling, or truncation signalling. Combined with 0% schema coverage on four parameters, the definition is workable but leaves an agent guessing on return shape and input formats.

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 0% across 4 parameters, so the description must compensate, and it does partially: 'by ID' -> message_id, 'account/mailbox' -> account_id and mailbox_path, 'bounded body length' -> max_chars. However it gives no format guidance for mailbox_path (a path-component array), no ID type, and none of the max_chars default (20000) or ceiling (100000), so real gaps remain.

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 a message by ID') plus the scoping dimension (account/mailbox), which is enough for an agent to distinguish it from the search_* siblings. It stops short of naming those siblings or contrasting the lookup-by-ID path against them, so it is clear but not fully differentiated.

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?

The phrase 'by ID' implies the tool is for retrieving a single already-known message, versus search_messages/search_inboxes for discovery, but no alternative is named and no when-not condition is given. Usage is inferable rather than stated.

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 establish read-only, non-destructive, non-open-world semantics, and the description adds material behavior the annotations cannot: per-account partial-failure handling ('a failing account is reported in its own entry without stopping the rest') and time-based skipping surfaced via not_reached, plus the pagination handoff through next_offset.

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?

Four short sentences, front-loaded with purpose and scope, followed by usage conditions, failure semantics, and the escalation path. No redundancy or 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 does useful work explaining return shape (per-account entries, not_reached, next_offset, account_id, mailbox_path). It is nearly complete, though the meaning of limit_per_account versus the first-page constraint is not spelled out.

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 0% across 4 parameters, so the description carries the burden. It explains query (empty lists everything) and unread_only behavior, but says nothing about scan_limit or limit_per_account, leaving half the parameters undocumented in both schema and text.

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 states a specific verb and resource plus scope: 'Search the inbox of every permitted account in one call: the first page from each.' It also differentiates itself from the sibling search_messages by naming it for deeper single-account work, so an agent can distinguish the two without opening either schema.

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 explicit when-to-use conditions ('Empty query lists messages; unread_only=true reviews what is new') and a concrete routing rule to the alternative tool ('To go deeper in one account, call search_messages with that entry's account_id, mailbox_path and next_offset'). Nothing about tool selection is left to inference.

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/destructiveHint/openWorldHint, so safety is covered. The description goes further with behavior annotations don't carry: a ~30-second scan cutoff on slow mailboxes, non-chronological mail order, and pagination instability under concurrent mailbox changes. That is genuinely useful disclosure for an agent driving a scan loop.

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?

Front-loaded with the core purpose, then three compact sentences of caveats, with no filler. The only friction is the 'next_offset' wording that doesn't line up with the schema's 'offset'.

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 7-parameter, no-output-schema search tool the description covers query semantics and scan/pagination caveats well, but leaves scan_limit, unread_only, and mailbox_path unexplained despite zero schema descriptions. Adequate but with clear gaps for an agent building correct calls.

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 0% across 7 parameters, so the description must compensate and largely does not. It clarifies query semantics (subject/sender, empty lists all) and implies pagination via offset, but says nothing about limit, scan_limit, unread_only, account_id, or mailbox_path, and the term 'next_offset' does not match the actual 'offset' parameter name.

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 (search), the fields searched (subject/sender, case-insensitive), and the scope (one mailbox), plus the empty-query behavior. It is clearly distinct from read_message but does not explicitly contrast itself with search_inboxes, leaving the sibling boundary to inference.

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?

Provides real operational guidance on continuation ('Continue with next_offset even if this page has no matches'), which is actionable, but never states when to choose this tool over search_inboxes or read_message, and gives no prerequisites. Usage is implied rather than framed.

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