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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds substantial non-obvious behavior: executables are refused even if disguised, text extraction is the only way to read a document without filesystem access, and file output depends on a configured download directory. There is no contradiction with the annotations.

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 a single dense paragraph rather than structured bullets, but every clause adds meaningful detail about listing, retrieval modes, document text extraction, download directory behavior, and security refusal. It is front-loaded with the key part_id distinction, though readability could be improved with segmentation.

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?

Despite the tool's complexity — six parameters, multiple modes, output schema, and security caveats — the description covers the essential invocation details: how to list, how to retrieve, how to read text, what happens with files, and the executable refusal rule. Nothing critical for correct use 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?

Schema description coverage is 100%, so the baseline is 3. The description enriches this by explaining the interaction between part_id and the listing call, the default auto mode behavior, and that offset and max_chars only apply with mode="text" — going beyond simple schema repetition.

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 that the tool lists attachments when part_id is omitted and returns a specific attachment when part_id is provided. It uses specific verbs (list, read, download) and names the resource (attachments), distinguishing it from sibling tools that deal with messages, mailboxes, or server info.

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 description explains when to use the listing mode versus the retrieval mode, and details the conditions for using mode="text", inline reading, or file download. It also notes that part_id must come from a listing call of this same tool. It doesn't explicitly name alternatives, but none of the siblings handle attachments, making the usage context clear.

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?

Beyond the readOnly, idempotent, and non-destructive annotations, the description adds valuable behavioral detail: the body is fenced as untrusted, a server-side security assessment is returned, and the tool does not change the read state. This is meaningful context that annotations alone do not convey.

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 sentences with no filler: the first packs the core behavior and return contents, and the second covers the optional thread expansion. Every sentence 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?

Given the output schema and annotations handle return structure and safety, the description is nearly complete for invoking the tool. The only notable gap is that it does not explicitly route the agent to get_attachments when actual attachment content is needed, though saying it returns the “list” of attachments implies this.

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 100%, so the schema already documents uid, mailbox, and include_thread. The description only restates include_thread’s effect in different wording, adding no essential new meaning 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?

“Fetches one message by UID” is a specific verb+resource statement, and the description clearly enumerates what is returned: headers, text body, security assessment, and attachment list. This distinguishes it from sibling listing tools (which return many messages) and from get_attachments (which would return attachment data rather than just a list).

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 description gives clear context: use this to fetch a single message by UID and optionally expand to its thread. It does not explicitly say when not to use it or name get_attachments as the alternative for attachment content, so it stops short of full routing guidance.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context by stating it reports configured mailbox, IMAP capabilities, permanent flags, keyword support, and enabled tool groups, helping the agent understand it as a configuration-discovery operation.

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 compact sentences with no filler. The first states what the tool reports, and the second gives a practical usage trigger. Every sentence 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 no-parameter informational tool with an output schema and safety annotations, the description fully covers what the tool does, what it reports, and when to call it. No critical guidance 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 has zero parameters and the schema coverage is 100%, so there is no parameter information for the description to add. The baseline of 4 applies, and the description appropriately focuses on output behavior rather than 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?

The description uses a specific verb ('Reports') and a clear resource ('what this account and server can do'), then enumerates the exact information categories returned. This distinguishes it from sibling mail-listing and retrieval tools, which operate on messages and mailboxes rather than server capabilities.

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 description gives an explicit when-to-use signal: 'Start here when a call fails for reasons that sound like configuration.' It does not mention alternatives or when not to use it, but the diagnostic context is clear enough to guide selection among the sibling tools.

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, idempotentHint, and destructiveHint false, covering safety. The description adds transparency about the exact output contents (counts, roles, hold-messages capability), and nothing contradicts the annotation metadata.

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 two sentences: the first states the function and output, the second gives a direct, actionable instruction. No unnecessary words or redundant details are present.

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?

Given that an output schema exists, the description does not need to enumerate return fields. It sufficiently explains the nature of the returned data and provides the key usage hint about the path, making the tool's full behavior clear.

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 has zero parameters, so there is no parameter ambiguity or need for additional description. Schema coverage is 100% by definition, and the description correctly omits any parameter references.

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 action (lists), the resource (every folder in the account), and the specific data returned (message counts, unseen counts, special-use roles, and whether it can hold messages). It is easily distinguishable from sibling tools that list messages or retrieve individual messages.

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 description includes practical guidance on using the returned 'path' verbatim for other mailbox-taking tools, which is a direct usage instruction. It does not explicitly name alternatives, but the distinct resource (mailboxes vs. messages) makes the appropriate context clear.

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 this as read-only, idempotent, and non-destructive. The description adds meaningful behavior beyond annotations: newest-first ordering, server-side application of filters, cheap large-folder searches, and that it returns only summaries. No contradiction with annotations.

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 tight sentences, each earning its place: core behavior, no-criteria default, performance note, and pointer to get_message. No filler or repetition of schema details.

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?

Given an output schema, strong safety annotations, and full schema coverage for 12 parameters, the description covers all essential context: ordering, filtering options, default paging behavior, performance, and how to retrieve full content. Nothing an agent needs to choose or call this tool 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?

Input schema covers 100% of parameters with descriptions, so the baseline is high. The description adds value by grouping filters (sender, recipient, subject, body text, date range, flags) and by explaining performance implications of server-side filtering, which goes beyond the schema entries.

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 verb ('Lists') and resource ('messages'), and specifies newest-first ordering plus optional filters. It distinguishes itself from get_message by noting 'Returns summaries only — use get_message for the body', but it does not explicitly distance itself from the sibling list_new_messages, whose name suggests a narrower scope.

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 description gives useful context: with no criteria it pages through the mailbox, and server-side filtering makes searches cheap. It provides an explicit alternative ('use get_message for the body') but does not mention when list_new_messages would be more appropriate, so exclusions are incomplete.

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?

The description fully discloses the mutating behavior (marking messages) and the non-effect on human read/unread state. It goes beyond the annotations, which only provide generic hints, by explaining the exact side effect and how to avoid it.

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 concise (two sentences), with no unnecessary words. All information is relevant and directly supports the tool's usage and understanding.

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?

The description covers purpose, side effects, parameter guidance, and distinction from human state. It provides all necessary context for an agent to decide when and how to use the tool, even though an output schema exists.

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 schema already describes both parameters, but the description adds context: limit's default from IMAP_MAX_MESSAGES and dry_run's preview behavior. This enriches the schema meaning without redundancy.

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: returning messages not yet handed over, sorted newest first, and marking them with an 'AiSeen' keyword. It also distinguishes this from human read/unread state, making the purpose 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?

The description explicitly mentions the side effect of marking messages and instructs to use dry_run to preview without marking. It also clarifies that human read/unread state is untouched, guiding when this tool is appropriate versus alternatives like list_messages.

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