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

The description discloses material beyond the annotations: content is attacker-authored and must never be treated as instructions, and the return shape varies by type — inline typed content for images, a marked untrusted block for text/JSON/XML, and a short-lived signed link or docker cp file path for other binaries. That return-shape and trust-boundary disclosure is exactly what annotations (readOnly/destructive/idempotent flags only) cannot 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?

A single front-loaded sentence that names the tool's function first, then the source of the part number, then the return variants. It is long and clause-heavy, but each clause carries distinct information; a light edit into two or three sentences would improve scanability.

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 return-value burden itself — and it does, explaining all three output modalities plus the no-HTTP-listener fallback. Combined with the prompt-injection warning, an agent has everything needed to call it and handle the result safely.

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 both parameters are documented there, including part 0 meaning the whole message. The description only restates that part numbers come from show's output, adding no syntax or edge-case detail the schema lacks. Baseline 3 applies.

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 ('Return one attachment or MIME part of a message') and anchors it to the sibling that produces the identifier ('by the part number shown in show's output'). An agent can tell this apart from show, text and files without opening any 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 clearly implies the prerequisite workflow: call show first to get part numbers, then call this. However, it never says when to prefer the sibling tools text or files instead of attachment, so the alternative-routing half of the guidance is missing.

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 cover the read-only, non-destructive profile, so the description only needed to add operational context — but it discloses nothing about cost, whether excluded folders are skipped, or that the result is just a tally. Note the odd idempotentHint=false on a pure read, which the description does nothing to clarify.

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. Nothing in it is redundant or misplaced.

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 simple read-only counter with fully documented parameters, the essentials are nearly there, but with no output schema the description should say that the result is a single count and not messages — an agent could otherwise assume it returns content.

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%, with the query syntax, account scoping, and include_excluded semantics all documented inline. The description adds nothing beyond that, which is the baseline 3 case.

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 ('Count') and resource ('messages matching a query'), so the intent is unambiguous. It does not distinguish itself from siblings like 'search' or 'ids', which take similar queries and return messages or identifiers.

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 guidance on when to use count instead of 'search' or 'ids', and no mention that it returns only a number rather than message content. The agent must infer the choice from the names alone.

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 closed-world/openWorldHint=false, so the safety profile is covered elsewhere. The description adds the useful detail that results are filesystem paths rather than message bodies or IDs, but says nothing about result limits, ordering, or what happens with large result sets (idempotentHint is false, which is unexplained).

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 wasted words. It is efficient, though it errs toward under-specification rather than being padded.

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 read-only three-parameter lookup with full schema coverage and no output schema, the description covers the essentials (paths returned, query-driven). It is still thin on result shape, ordering, and limits, and gives no hint about the cost of broad queries.

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 query syntax, account scoping and include_excluded semantics are fully documented in the schema. The description contributes nothing beyond restating that a query drives the result, so baseline 3 applies.

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 (Return) and a specific resource (maildir file paths) plus the matching condition, which distinguishes it from siblings like ids, search, show and text that return other representations. It stops short of naming an alternative explicitly, so sibling differentiation is 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 reach for this tool versus the many siblings (ids, search, show, text, thread). Nor does it mention the default exclusions (junk/trash) or any prerequisite, leaving the agent to infer usage purely from the tool 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, openWorldHint=false, so safety and scope are covered structurally. The description adds value by disclosing that sync timestamps and last-error state are included, but says nothing about result size, pagination, or ordering across accounts.

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. It is perhaps slightly dense with four enumerated items, but every clause carries information about the return payload.

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 with no output schema, the description covers the shape of the returned data reasonably well. It stops short of explaining ordering, nesting of folders under accounts, or how errors are represented, which an agent would still have to discover.

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 this is an unfiltered top-level listing with no scoping arguments to worry about.

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 enumerates the resources returned: accounts, folders, index tags, plus each account's last sync and last error. That is clear enough to know what the tool produces, but it does not differentiate against siblings like status or files, and the tool name 'folders' understates that accounts are the primary resource.

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 statement of when to use this versus alternatives such as status (which may also report sync state) or files. The agent must infer the use case entirely from the resource list.

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 structurally. The description adds nothing beyond the annotations — no note on ordering of results, whether ids are notmuch message ids, or that default search excludes junk/trash (deferred to the schema).

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 sentence with zero filler, front-loading the result type. Its brevity verges on under-specification rather than wordiness, so it is efficient but not exemplary.

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 tool whose output is a bare list of ids meant to be chained into other tools, the description omits result ordering, whether ids are stable/unique, and how they relate to the show/thread siblings. No output schema exists, so the description should carry more of this burden.

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% and the schema documents the notmuch query syntax, account scoping, and the include_excluded caveat in detail. The description names only 'query', so it neither adds nor detracts from what the schema already provides — 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 result ('Return the message ids') scoped to 'matching a query', which tells an agent this yields identifiers rather than full messages. It does not differentiate from siblings like search or count, which is the only thing missing for a 5.

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 statement of when to prefer this over search, count, or show, and no hint that the returned ids are the natural input to show/thread. The only implied usage is that a query is 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?

Annotations already flag a non-read-only, non-idempotent, open-world mutation, and the description adds genuinely new behavior: a bounded 20s wait, a possible 'still running' outcome, and the downstream reindex effect. It does not say whether a repeat call restarts or resumes work, nor what happens to data mid-reindex, which keeps it below a 5.

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 with zero filler; the scope ('every folder... all accounts') is front-loaded before the timing caveat, which is where the agent needs it for a long-running call.

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 burden of describing the outcome, and it does so for the main branch (running vs. done). It leaves the completion response shape and the effect of the reindex on existing indexes underspecified, which is a small remaining gap given the annotations already cover safety.

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 is fully documented in the schema, including the omit-to-sync-all default and the reference to 'folders and status report' naming. The description's blanket 'one account or all accounts' only restates that, so the baseline of 3 for high coverage applies.

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+resource ('Sync every folder of one account or all accounts now, then reindex'), covering both the sync and the reindex step. That is concrete enough to separate it from sibling read tools like status, search, and folders 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?

Gives a clear operating context: it waits up to 20 seconds, and if the pass is still running the agent may either call again or search the indexed data. That is actionable guidance, but it never explicitly contrasts the tool with the 'status' sibling for checking progress, so the routing is implied 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 cover the safety profile (read-only, non-destructive, closed-world). The description adds useful behavior beyond annotations by stating that results are thread summaries in JSON and by specifying the supported query language.

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 compact sentences with no filler. The purpose, return shape, and query syntax are front-loaded and directly useful.

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 five-parameter read-only search tool with full schema coverage, the description supplies the essential return shape and query language. It stops short of workflow guidance such as using thread/show to expand a result, and does not describe summary fields, so it is not fully complete.

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 schema already documents limit, offset, account, include_excluded, and the notmuch query syntax in detail. The description repeats the query syntax rather than adding new parameter meaning, so the 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 ('Search') and resource ('mail'), and adds the return type ('thread summaries as JSON'). It does not explicitly differentiate from siblings such as thread or show, but the summary-vs-detail distinction is reasonably implied.

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 'Search mail' implies the general usage context, but there is no explicit when-to-use, when-not-to-use, or alternative such as thread/show for expanding results. The agent must infer routing from the sibling tool names.

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 safety is covered. The description adds that the body is decoded and output is JSON, which is useful beyond the structured fields. However, it never mentions the truncation/pagination behavior or the default exclusion of junk/trash mail, both of which shape 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?

A single sentence with zero waste; the resource (one message) and the return shape (headers plus decoded body as JSON) are front-loaded.

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 the right minimum by saying what comes back (headers and decoded body, JSON). Since annotations and a fully documented schema cover safety, pagination and folder defaults, only the missing mention of chunked reading keeps this below 5.

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% — the id, limit, offset and include_excluded parameters are each fully documented in the schema, including the [truncated] marker convention. The description adds nothing about parameter formats or constraints, so the baseline 3 applies.

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 — 'Show one message' — and specifies the payload ('headers and decoded body, as JSON'), which separates it from a plain body-reader. It does not name the sibling tools (text, thread, attachment) it must be distinguished from, so an agent still has to infer the boundary.

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 by the required 'id' parameter: fetch a single known message by Message-ID. There is no explicit when-to-use versus text/thread/attachment, and no statement of prerequisites. Some operational guidance (truncation resumption, junk/trash opt-in) exists, but it lives in the schema rather than the description.

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 and destructiveHint=false, so the safety profile is covered. The description's main addition is the enumeration of reported fields, which is useful. It is silent on scope (does 'per account' mean all accounts or a selected one, given zero parameters?) and on whether errors and backoff are aggregated or listed individually. Note that idempotentHint=false is unusual for a passive status read, but the description neither confirms nor contradicts 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?

Two sentences with zero waste: the first front-loads what is reported (the field list), and the second front-loads when to call it. Nothing is redundant with the schema or annotations.

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 correctly compensates by enumerating the fields returned (sync completion, last success, message count, errors, backoff). For a zero-parameter read-only diagnostic tool, this is exactly the information an agent needs.

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?

With zero parameters, the schema has nothing to document, so the baseline of 4 applies. The description's mention of 'per account' slightly clarifies output scope, though it raises a mild question about why no account parameter exists.

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 ('report') and resource ('sync health per account') and then enumerates the exact dimensions reported: first full sync completion, last successful sync, messages indexed, errors, and backoff. This is precise enough that an agent can distinguish it from the 'refresh' sibling, which presumably triggers a sync rather than describing its state.

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 a clear triggering condition: call it when results look incomplete, or to check whether the server is fully functional yet. It does not explicitly name alternatives (e.g., refresh) or state when not to call it, which keeps it short of a 5.

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, openWorldHint=false, so the safety profile is covered. The description adds one behavioral fact – HTML is converted to plain text – but says nothing about truncation, hostility of junk/trash, or what the conversion loses, all of which the schema, not the description, carries.

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 zero filler; every word (plain-text, body, one message, converting HTML) carries information.

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 four fully documented parameters, an explicit required id, and annotations covering the safety profile, the definition is nearly complete; the return value is captured by 'plain-text body'. Only pagination/truncation behavior is left entirely to the schema.

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 id, limit, offset, and include_excluded are fully documented in the schema; the description adds no syntax, format, or interaction detail beyond it. Baseline 3 is correct when the schema does all the work.

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 (return) and resource (plain-text body of one message) plus the transformation (converting HTML), which separates it from siblings like attachment or thread. It does not explicitly name a sibling it is not, which keeps it just under a 5.

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 statement of when to use this tool versus show, thread, or attachment, nor any prerequisites (e.g., message must be reachable). The single sentence describes only what happens, leaving selection to inference 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 readOnly, non-destructive, closed-world behavior, so the bar is lower. The description usefully adds that junk/trash replies are excluded by default and that include_excluded changes this, which is meaningful behavioral context beyond 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?

Two concise sentences, front-loaded with the primary action and followed by the key default-filtering behavior. 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 simple read-only thread retrieval tool with fully documented parameters and safety annotations, the description is largely complete. A minor gap is that it does not mention pagination or the shape of the returned thread, though the input schema covers limit/offset.

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 all four parameters in detail. The description repeats the include_excluded default behavior but adds no syntax, format, or usage detail 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: 'Show the whole thread containing a message.' It is clearly distinguishable from sibling tools like 'show' or 'search' by scope, though it does not explicitly name alternatives.

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 implies the use case of retrieving a full thread from a message ID, and explains the default filtering behavior. However, it does not explicitly say when to use this tool versus 'show', 'search', or 'text', nor does it state exclusions or alternatives.

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