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

Beyond the read-only and idempotent annotations, it discloses important behavior: chunked reads, metadata and local paths, continuation rules, and the distinction between unavailable extracted text and an empty original attachment. These are meaningful operational details that help the agent avoid misinterpreting absence.

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 front-loaded with purpose and then gives usage and caveats in short, purposeful sentences. There is little redundancy, and the continuation guidance is placed where an agent needs it.

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 tool is moderately complex with a full schema, complete schema descriptions, annotations, and an output schema. The description fills the remaining gaps around chunked reading, continuation, missing text, and missing files without needing to repeat return-value details.

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 complete, so the schema already documents all parameters. The description still adds useful cross-parameter semantics by explaining where file, key, and connection come from and that continuation requires the same connection, key, and file with offset=nextOffset.

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: reading an attachment's saved extracted text as Markdown in chunks. It also explicitly distinguishes this from on-demand conversion, so the agent understands the tool reads existing extraction rather than creating it.

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 clear sourcing guidance: obtain file from getMessage attachments or a search hit's snippetAttachmentFile, and reuse the same connection and key. It also explains continuation via offset=nextOffset and when to stop, though it does not name a specific alternative tool for on-demand conversion.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds behavior the annotations can't: pagination continues only the body while headers and the attachment list are re-returned each call, and an absent body means saved body text is unavailable rather than the original being empty. That last point is a genuine anti-misinterpretation warning.

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 paragraphs with the return shape front-loaded and the escape hatches second. Minor redundancy with the offset/nextOffset schema text, but nothing is padding.

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?

Output schema exists so return values need no prose, and the description still covers the edge cases an agent would otherwise get wrong: body-only pagination, empty-body interpretation, archive-extracted attachments and the parent field. Nothing needed to call 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?

Schema coverage is 100%, so key, offset, maxChars and connection are already documented, including the nextOffset continuation rule. The description restates that rule and adds only the `file` vs `name`/`path` disambiguation, which applies to the sibling tool rather than this one's parameters.

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?

Opens with a specific verb and resource plus the exact payload ('headers, a body chunk as Markdown, and an attachment list'), which no sibling tool claims. It also implicitly separates itself from getThread and getAttachment by naming them for those respective jobs.

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?

Explicitly routes adjacent needs: attachments go to getAttachment with the same connection/key and file=attachments[].file, the conversation goes to getThread. It also gives the continuation rule (keep connection and key, follow nextOffset, stop when absent), so an agent knows when to call again versus call elsewhere.

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 read-only, idempotent, non-destructive, but the description adds substantial substance beyond them: cards come back without bodies, ordered oldest first with undated last, only locally indexed messages appear, messages are linked by Message-ID/In-Reply-To/References rather than subject or participants, and recognized duplicates are collapsed into a copies field with totals counting groups.

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 paragraphs, front-loaded with the scope and ordering before the follow-up instructions. Nearly every sentence carries load, though the trailing clause 'total and paging count groups' is terse enough to be slightly opaque.

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 shape needn't be spelled out, yet the description still covers the semantics an agent needs: body-less cards, ordering, duplicate collapsing, and header-based threading. Combined with annotations covering the safety profile, nothing needed to call it correctly is absent.

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 100% and already documents key, limit range and cap, and the offset/nextOffset continuation protocol, so the baseline applies. The description reinforces that the 'key' is a card key from the returned list rather than a Message-ID header, but adds no new syntax or constraints 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?

States a specific verb and resource — 'List the locally indexed conversation containing a message, across all folders of one connection' — which cannot be confused with listMessages or search. It also distinguishes itself from getMessage by positioning that sibling as the follow-up for reading bodies.

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?

Explicitly routes the agent: use this to enumerate the conversation, then call getMessage with the same connection and each card's key. It gives a paging stopping rule ('Stop when there is no nextOffset'). What's missing is an explicit statement of when NOT to use it (e.g., a single-message read or a subject-based grouping), though the linking-by-headers note implies the latter.

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 adds meaningful behavior beyond the annotations: it reads local configuration without signing in, and it warns that localDataAvailable does not imply complete or up-to-date mail. Those details help an agent interpret and trust the result correctly.

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 purpose is front-loaded in the first sentence, followed by usage and field semantics in a compact sequence. Every sentence carries actionable information, with no redundant restatement of the name or title.

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 listing tool with an output schema and annotations covering safety, the description is complete enough. It explains when to call it, how to use its output, and an important caveat about local data coverage.

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?

There are no input parameters, so parameter semantics are inherently minimal and the schema has nothing to document. The description instead explains key output field meanings, which is useful but outside the parameter dimension.

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: 'List the configured mailboxes.' It also distinguishes the tool from siblings by explaining that it should be called first when the mailbox is unknown and that its name field feeds the 'connection' argument of every other tool.

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 an explicit trigger: 'Call first when the mailbox to use is not known yet.' It also redirects agents to listFolders and syncStatus for coverage inspection, which clarifies an important alternative path.

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 readOnly/idempotent/non-destructive, and the description goes well beyond them by disclosing the meaning of synced=false (a completed folder sync not recorded, messages may be missing) and the subtle caveat that synced=true does not guarantee current mail. That is exactly the non-obvious data-freshness behavior an agent needs before trusting results.

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?

Five short sentences, front-loaded with what the tool returns, then downstream usage, then freshness caveats, then negative scope. No sentence is redundant with another or with the structured fields.

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 shape needn't be described; the description instead fills in the interpretive context the schema cannot carry (sync semantics, cross-tool key usage, non-discovery). Nothing an agent needs to call this 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 single parameter has 100% schema coverage and already points to listConnections, so baseline would be 3. The description adds real meaning by stressing one connection and 'keep the same connection', signalling that folder keys are scoped to a connection and misusing this yields wrong lookups.

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 (list locally known folders) plus exactly what is returned (folder keys, paths, local indexed message counts). It also scopes itself negatively against a hypothetical discovery tool ("does not discover folders on the server") and routes the folder key to listMessages/search, so an agent can place it among siblings without opening the 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?

Explicitly tells the agent what to do with the output ("Pass a folder's key as folder to listMessages or search; keep the same connection") and what to consult when freshness matters (syncStatus). It lacks an explicit when-not-to-call statement, though the non-discovery scoping sentence covers most of that gap.

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 readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond them: undated messages sort last without bounds but are excluded with bounds, results are cards without bodies, every stored copy is counted separately whereas search and getThread group recognized copies, and read/flagged reflect the last sync observation. These are non-obvious semantics that materially change how results should be interpreted.

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 what the tool returns and how it differs from search, then the follow-up path, then the subtle copy-counting nuance. No filler and no repetition of schema field descriptions.

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, yet the description still sketches the card shape and the read/flagged provenance, which is the right level. Between the description, the 100%-covered schema, and the annotations, an agent has everything needed to call it correctly and chain into getMessage/getThread.

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 100%, so the baseline is 3; the description earns extra credit by adding cross-parameter behavior the schema does not state, namely the ordering and exclusion rule for undated messages at the since/until boundaries. It stops short of restating formats, which is appropriate since the schema already carries them.

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 (browse locally indexed messages), the scope (one folder), the ordering (newest first), and the optional date filter. It also explicitly distinguishes itself from 'search' and from the card-reading tools getMessage/getThread, so an agent can route without opening sibling schemas.

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?

Gives explicit when-to-use-elsewhere rules: 'For keyword search use search; for a date range across all folders use search without query.' It also names the follow-up path (pass a card's key plus the same connection to getMessage, or to getThread), which is exactly the alternative-selection guidance an agent needs.

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, openWorldHint and destructiveHint=false, so safety semantics are covered. The description nevertheless adds real substance beyond them: the corpus is limited to synced and indexed content, an empty result does not prove absence, morphology limits for Russian/English, ranking direction per mode, and deduplicated "recognized copies" counted in total and paging. Not a 4-5 because it does not quantify index freshness or the sync dependency beyond a passing mention.

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?

Purpose is front-loaded, followed by search semantics, then how to read a hit, then result-shape notes; every paragraph has a job. It is dense but slightly over-packed — the getMessage/getAttachment sentences repeat 'using the same connection' twice and could be tightened.

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 8 parameters, an output schema and rich annotations, this covers what remains: query syntax and its limits, date-header semantics, the two result orderings, snippet/copy structure, and the cross-tool hop needed to fetch an attachment. An agent can call it correctly and interpret the response without further guessing.

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 100%, so the schema carries the per-parameter detail and the description correctly does not repeat it. What it adds is search-quality semantics for query (word forms, synonyms, no field-prefix syntax) and a concrete paging procedure, which meaningfully explains how to drive the parameters rather than restating their types.

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?

Opens with a specific verb and resource plus scope: "Search locally synced messages in one connection." It immediately delineates two modes (text query vs date-only listing) and routes the agent to getMessage/getAttachment for follow-up, which distinguishes it from listMessages/listFolders without needing their schemas.

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?

Explicit when-to-use rules: supply query for text search, omit it when only since/until are given, and try fewer words or the other language if results are sparse. It also names the alternative reading tools (getMessage, getAttachment) and the exact conditions and arguments that select them.

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?

Goes well beyond the annotations by documenting the async state machine: status=started means launched not finished, lockedByOtherProcess means no sync was started and may be an offline command, and refused requires user action in a terminal. The 'remote mailbox is not changed' clause reconciles with readOnlyHint=true and clarifies that only the local copy is written.

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 purpose and scope in the first sentence, then organized into usage and state-handling sections with no filler. The dense state paragraph is justified by the tool's async behavior, though it could be tightened slightly for scanning.

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 values need no explanation, and the description still supplies the operational envelope: latency warning ('the first sync can take a long time'), background execution, per-status guidance, and a lock-conflict case. Nothing critical for correct invocation 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 coverage is 100% and the single parameter is already documented as 'Connection name from listConnections'. The description only refers to 'the same connection' when describing syncStatus polling, adding no new format or constraint information. Baseline 3 is appropriate.

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 ('Refresh one connection's local mail copy from the mail server') and enumerates exactly what is propagated (new messages, removals, moves, read/flag states), plus an explicit non-effect ('The remote mailbox is not changed'). This clearly separates it from syncStatus, which only reports progress.

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?

Gives an explicit trigger ('Call when the user needs newer mail than the local copy'), an explicit anti-pattern ('do not call sync again to check progress' → use syncStatus with the same connection), and a failure-path instruction ('For refused, relay message to the user and do not retry'). No inference required.

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?

Goes well beyond the readOnly/idempotent annotations: enumerates every state and phase value, warns that checkingLocal/checkingFolders can stall for minutes with no progress, notes other tools may see incomplete results while running, clarifies that completed can still have failed>0 (count is of messages, not runs), and explains the signInRejected recovery path. No contradiction with annotations — non-destructive read is consistent.

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?

Dense but front-loaded: the core read-only claim and the state/phase glossary lead, with edge-case handling following. Some sentences (timestamps caveat, phase latency note) are closely packed, but each conveys distinct operational information rather than repeating the schema.

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?

Output schema exists, yet the description still explains the semantics of the key return fields (state, phase, failed, error, signInRejected) that an agent needs in order to act. Combined with the latency and recovery guidance, nothing necessary for correct invocation or follow-up behavior 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?

Only one parameter (`connection`) and schema coverage is 100%, with the schema itself pointing at listConnections for valid values. The description adds no further parameter semantics, which is acceptable here since the schema fully covers it, but there is no value added beyond it.

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+resource: reads progress/result of the current or last sync, and explicitly disclaims what it does not do (start a sync, contact the mail server). That negative clause is exactly what separates it from the sibling `sync` tool 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?

Gives clear operational context: 'Check state to decide whether to keep waiting', and warns that repeated sync calls cannot recover a signInRejected failure — the agent should instead tell the user to fix credentials in a terminal. It stops short of explicitly naming `sync` as the tool that actually starts a sync, leaving that inference to the reader.

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