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

Annotations already declare readOnlyHint=true, but the description adds valuable behavior: 'without fetching any of them' clarifies that no message content is retrieved, and 'cheap way' signals performance characteristics. This goes beyond the annotation's basic safety profile, though it doesn't cover all possible edge cases.

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 the core statement, followed by usage context and an Args section. Every sentence adds value—examples for query syntax, scope behavior, and count semantics are all relevant. No fluff.

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 count tool with no output schema, the description sufficiently implies the return value (a count) while covering query syntax, scope, and count modes. The mention of default scope and examples of date ranges makes it complete for the tool's complexity.

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?

Even though schema property descriptions are absent (0% coverage), the description thoroughly explains each parameter: the query syntax with notmuch examples and date ranges, the scope default behavior, and the count options ('messages' or 'threads'). This fully compensates for the schema's lack of descriptions.

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 opens with 'Count messages or threads matching a query'—a specific verb and resource that clearly states the tool's function. It distinguishes itself from siblings by explicitly stating it doesn't fetch matches and is not a substitute for mail_search.

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 explicit usage context: it's a 'cheap way to check whether a correspondent, subject or thread exists' before running a full mail_search, and explicitly says 'Not a substitute for mail_search when you need to see the matches themselves.' This gives clear when-to-use and when-not-to-use guidance relative to alternatives.

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 mark the tool as readOnlyHint=true and openWorldHint=false, which covers the safety profile. The description adds behavioral context beyond annotations: it explains the search scope (across a whole search), the `limit` parameter's truncation behavior ('when it truncates the total is still reported'), and scope defaulting. It does not discuss auth or return format, but for a read-only search tool this is adequate.

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 well-structured: a one-sentence purpose, then usage guidance with examples, a note about query-level filtering, and an Args section. Every sentence adds value—no filler or repetition. The front-loaded purpose makes it easy to scan, and the Args section is formatted for quick reference.

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 4 parameters, no output schema, and no enums, this description covers the core usage well: what the tool does, when to use it, parameter semantics, and limit behavior. It does not describe the structure of returned attachment rows (e.g., fields like filename, size, message ID), which could be helpful given there is no output schema. Still, the lack of such detail does not prevent correct invocation for the described purposes.

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%, so the description must fully compensate. It does: each parameter (query, scope, type, limit) has a clear explanation with examples and default behavior. For instance, `type` is defined with categories and raw extensions, and `limit` clarifies that omission means all results while truncation still reports the total.

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 opens with 'Find attachments across a whole search, not just within one message', which is a specific verb+resource+scope statement. It clearly distinguishes itself from the sibling mail_list_attachments by explaining the different scope ('a whole search' vs 'a single message').

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance with concrete examples ('all invoices from 2025', 'which PDFs did I get from the accountant') and an explicit alternative for single-message cases: 'use mail_list_attachments instead'. It even notes the notmuch query-level filtering alternative (attachment:*.pdf, tag:attachment).

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?

While annotations provide readOnlyHint=true, the description adds critical behavioral details: it explains that query is a notmuch query, describes the three output modes and their semantics, and discloses limit truncation behavior ('when it truncates the total is still reported'). It also surfaces a subtle pitfall about display-name matching, which goes well beyond annotation data.

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 compact and front-loaded with the core purpose, then usage rationale, then detailed parameters. Every sentence earns its place—there is no fluff or repetition. The Args block follows a consistent, scannable format, making the information easy to parse.

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 parameters and no output schema, the description covers all essential aspects: purpose, usage context, parameter semantics, and even edge-case behavior (unreliable direct matching, truncation reporting). It provides enough information for an agent to select and invoke the tool correctly without external docs.

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 input schema provides no descriptions (0% coverage), so the description carries the full burden. Each parameter receives thorough explanation: query with an example, scope with a reference to mail_list_scopes, output with explicit modes and meanings, and limit with default and truncation semantics. This fully compensates for the schema's silence.

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 opens with a clear, specific verb-resource pairing: 'Resolve a name or query into the concrete email addresses behind it.' It distinguishes itself from sibling tools by focusing on address resolution rather than message search, read, or count operations. The purpose is immediately understandable and not a tautology.

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 tells the agent when to use this tool: 'Call this tool first whenever you only have a name, then search or count using the address(es) it returns.' It also warns against the unreliable alternative of using from:<name> directly in search, providing concrete when-not-to-use guidance and setting expectations for subsequent steps.

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 behavioral context beyond the readOnlyHint annotation by stating that the tool returns metadata (part index, filename, content type, size) and not content. This is useful, though the annotation already covers safety.

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 and well-structured: it starts with the main purpose, then gives usage guidance, and ends with an Args section. Every sentence earns its place without unnecessary fluff.

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 one-parameter tool without an output schema, the description is complete: it lists the return fields, states what it does not return, and positions it relative to sibling tools. No critical information 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?

With 0% schema description coverage, the description compensates by explaining that message_id should be 'as seen in mail_search/mail_read_thread output', providing source context. This adds meaningful value over the schema alone.

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: 'List a message's attachments (part index, filename, content type, size)'. It uses a specific verb and resource, and explicitly distinguishes itself from sibling tools like mail_read_attachment by noting it does not return content.

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 explicit usage guidance: 'Call this before mail_read_attachment to learn valid part_index values'. It also clarifies what the tool does not do ('does not return attachment content itself'), helping the agent choose the right tool.

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 provide readOnlyHint=true. The description adds value by specifying the output includes notmuch query and description, behaviorally enriching beyond the annotation.

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: first states purpose, second provides usage guidance. Front-loaded, no wasted words, perfectly concise.

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 list tool with no output schema, the description explains what is returned and why to use it. Could be more explicit about output format, but sufficient given no 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?

Tool has 0 parameters with 100% schema coverage (empty schema), so description does not need to cover parameter meaning. Baseline for 0 params is 4.

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 it lists configured scopes with their notmuch query and description, and explicitly mentions its purpose for discovering valid scope values for other mail tools. This distinguishes it from all sibling tools.

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 instructs to call this tool to discover valid scope values for mail_search/mail_count/mail_tag instead of guessing, providing clear context and a specific alternative.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safe-read nature is covered. The description adds valuable behavioral context: both directions sort oldest first because 'age is the point', the 'waiting' direction requires identity addresses and raises an actionable error if missing, and the limit parameter still reports the total when truncating. This is strong supplementary transparency 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?

The description is organized into clear paragraphs and an Args section. Every sentence earns its place: both directions are explained with use cases, sorting is justified, the config dependency for 'waiting' is disclosed, and the relationship to mail_search is stated. It is thorough but not bloated, with no redundant phrasing.

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 tool's complexity (two directions, config dependency, sorting, and four parameters with nuances), the description is fully complete. It covers return-ordering behavior, error conditions, parameter semantics, and when to use alternatives. Although there is no output schema, the description notes that the total is reported even when truncating, which addresses response expectations.

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%, so the description must carry the full burden, and it does. Every parameter is explained with concrete examples: direction lists values and meaning, older_than gives formats like '14d', scope references mail_list_scopes for configuration, and limit explains its default and truncation behavior. This fully compensates for the schema's lack of descriptions.

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 opens with 'Threads that need attention: mail owed by you, or mail you are waiting on,' which specifies the exact verb (list threads needing attention) and resource (mail threads). It differentiates from the sibling mail_search by explicitly stating 'This is not a substitute for mail_search when you want to see the messages themselves,' making its purpose unmistakable.

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 provides explicit usage scenarios: direction='owed' is for 'what do I still need to reply to' and direction='waiting' for 'who owes ME a reply'. It also names the sibling alternative (mail_search) and explains when not to use this tool, saying it is only for triaging outstanding mail, not for viewing messages.

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 reinforces the readOnlyHint annotation by stating it 'computes' and 'writes nothing.' It adds behavioral details such as quoting behavior ('> ' for replies, labelled forwarded blocks for forwards), subject prefix rules ('Fwd:' exactly once), and header handling (In-Reply-To/References). This goes well beyond the annotation alone.

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 a one-sentence summary, followed by a read-only note and a direct pointer to mail_create_draft. The Args section is cleanly formatted and every sentence adds value – no fluff or repetition of schema metadata.

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 tool has no output schema and only three parameters, the description covers the tool's purpose, output (headers and body), mode variations, and the follow-up action. It also clarifies the read-only nature, making it complete for an agent to select and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description compensates by defining message_id as a Message-ID from mail_search/mail_read_thread output, quote as including the original body with specific formatting, and mode with three detailed options including Mail-Followup-To semantics. Each parameter is fully explained beyond the schema's type/default fields.

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 opens with a specific verb ('Derive') plus the resource ('reply/forward headers and the quoted or forwarded body'), clearly distinguishing it from read-only tools like mail_read_message and mail_read_thread. It also names the output artifacts (To/Cc/Subject/In-Reply-To) and the body format, making the tool's function unmistakable.

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 explicitly instructs the agent to pass the result to mail_create_draft for persistence, and it specifies that this tool itself writes nothing, establishing when to use it versus the draft-saving alternative. The mode parameter is explained with concrete semantics (reply/reply-all/forward) and pitfalls (honoring Mail-Followup-To), giving clear usage context.

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

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

Annotations only indicate readOnlyHint, but the description goes far beyond by detailing content-type dispatch (pdftotext, Pandoc/LibreOffice, etc.), image handling with downscaling/refusal, error behavior for unsupported formats, and calendar invite summary rendering. This is rich behavioral context with no contradiction.

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 yet complete, starting with a clear summary, followed by necessary technical details, and ending with parameter definitions. No sentence is wasteful; the structure is logical and 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 covers expected return formats (text, image, summary) and error cases. It also notes prerequisites and limitations, making the tool's behavior fully comprehensible for an agent.

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?

Although schema coverage is 0%, the description includes an 'Args' section that explains both parameters. message_id is tied to specific sources ('as seen in mail_search/mail_read_thread output') and part_index is defined as '1-based part index from mail_list_attachments', adding meaning the schema lacks.

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 opens with a clear, specific statement: 'Read one attachment: text, PDF, image, office document or calendar invite.' This identifies the verb, resource, and scope, and distinguishes it from sibling tools like mail_list_attachments and mail_read_message by focusing on attachment content.

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 guidance is provided: 'Call mail_list_attachments first to get a valid part_index.' It also clarifies unsupported types ('Archives and other binary formats are not supported') and explains the prerequisite, making the when-to-use and when-not-to-use 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 indicate readOnlyHint=true, and the description adds meaningful behavioral context beyond that: it describes the response_format behaviors ('concise' vs 'detailed') and discloses that the detailed body is truncated by a configured limit. This goes beyond the annotations, though it could have mentioned error handling or idempotency.

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 moderately sized and well-structured, starting with a one-line summary, then a usage note, then an Args list. Every sentence contributes value with no fluff, though it is slightly longer than the minimal needed.

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 only two parameters and no output schema, the description adequately covers what the tool returns (headers and body), the output format choices, and how it relates to sibling tools. It provides enough information for an agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero property descriptions (0% coverage), but the description's Args section fully compensates. It explains message_id format (with/without angle brackets or 'id:' prefix) and the two response_format options with their effects. This adds substantial 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?

The description clearly states the tool returns a single message's headers and body, using a specific verb and resource. It also distinguishes itself from the sibling mail_read_thread by explicitly noting the difference between a single message and an entire conversation.

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 provides explicit guidance on when to use this tool ('for one specific message') and names the alternative for conversations (mail_read_thread). It also includes parameter-specific usage details, such as how to format message_id and the two response_format options.

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 openWorldHint=false. The description adds substantial behavioral context beyond this: ordering, message separators, response_format differences ('concise' vs 'detailed'), handling of the 'thread:' prefix, and the caveat about long threads and configured limits. No contradictions 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?

Every sentence is functional: output format, usage context, alternatives, and parameter details. The structure is clear, front-loaded with the primary purpose, and no redundant wording despite being more detailed than typical.

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 a read-only operation with two parameters and no output schema. The description covers output ordering, format, parameter semantics, and usage guidance. It is complete for the tool's complexity and leaves no critical gaps.

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%, so the description fully carries parameter documentation. It explains thread_id as 'A thread identifier as returned by mail_search (with or without the 'thread:' prefix)' and response_format with concrete examples of what each option returns. This exceeds baseline for zero-coverage 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?

The description opens with a specific verb+resource: 'Return every message in a thread, oldest first, with '--- [N/M] ---' separators.' It clearly distinguishes from siblings by explicitly naming mail_read_message for single messages and mail_thread_overview for long threads.

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 explicit when-to-use ('Use this once mail_search has identified a thread_id'), when-not-to-use ('For a single message, use mail_read_message instead'), and an alternative strategy for long threads ('consider calling mail_thread_overview first'). This fully covers the decision space.

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?

It discloses the underlying heuristic (normalized-subject overlap + participant overlap), the configured default scope, and both false-negative and false-positive behaviors. It also explains the limit parameter's truncation behavior and that the total is still reported, adding non-obvious context beyond the readOnlyHint annotation.

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 well-organized: purpose paragraph, heuristic/limitations paragraph, and a clear Args list. Each sentence adds meaningful information without redundancy; it is detailed yet entirely relevant.

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 lacking an output schema, the description conveys that the tool returns related thread leads and mentions the truncation total reporting. It also provides reliability caveats, giving the agent sufficient context to invoke the tool and interpret its results appropriately.

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 provides no parameter descriptions, but the Args section fully explains thread_id (including the optional 'thread:' prefix) and limit (default null, capping behavior, and truncation reporting). This completely compensates for the 0% schema-description coverage.

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 opens with a specific verb+resource: 'Find other threads that might be the same topic coming up again.' It clearly distinguishes the tool from siblings by focusing on related-thread discovery rather than general search or reading. The heuristic-vs-semantic contrast further differentiates it from mail_search.

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 states how to use the results: 'Treat the result as a lead to check with mail_read_thread, not as a definitive answer.' It also contrasts with semantic search, giving clear context about when this tool is appropriate and what its limitations are.

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?

Discloses paging behavior, truncation reporting, mixing of matched/unmatched authors in the authors column, and output legend. Despite readOnlyHint being already declared, the description adds substantive behavioral context beyond the annotation.

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?

Well-structured with usage scenarios up front and a clear Args list. Bullet points make parameters easy to scan, and every sentence adds value without unnecessary verbosity.

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-param search tool with no output schema, the description covers return values, paging, granularity options, parameter semantics, and alternative tools. It is self-sufficient and 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?

With 0% schema description coverage, the description fully compensates by explaining all 7 parameters with examples, defaults, and syntax hints. The query parameter even points to external documentation and gives date range examples.

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 searches notmuch and returns a paged summary at thread or message granularity. It distinguishes from siblings like mail_read_message, mail_read_thread, and mail_list_addresses by explicitly stating what this tool does not do.

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 explicit when-to-use guidance for granularity='threads' vs 'messages' with concrete examples. It also names alternatives for fetching full bodies and address lookup, including a warning about from:<name> matching notification mail.

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 annotations already declare readOnlyHint=true, and the description adds valuable behavior: output structure, layout semantics ('tree' vs 'flat'), and token efficiency compared to mail_read_thread. It does not contradict annotations, and adds meaningful context beyond the safety hints.

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 appropriately sized and well-structured: it starts with the output format, then gives usage guidance, then details arguments. Every sentence earns its place with no redundant or vague 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?

The description is highly complete for a read-only overview tool: it specifies output fields, layout options, usage context, and parameter origins. Minor gaps like pagination or max message limits are not addressed, but the description is sufficient for the tool's purpose.

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 0% schema description coverage, the description fully compensates. thread_id is explained as a value from mail_search with/without 'thread:' prefix, and layout is thoroughly described with tree/flat semantics and its relation to mail_read_thread's numbering. This adds substantial meaning beyond the schema's bare 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?

The description clearly states the tool's output format ('One line per message: index, date, size, from, and a marker when the subject changes') and identifies the resource as a mail thread overview. It distinguishes itself from sibling mail_read_thread by emphasizing its lightweight, token-efficient nature.

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 guidance is provided: 'Use this before mail_read_thread on any thread you have not looked at yet' and 'Do not use it in place of mail_read_thread when you already know you need the full content.' This clearly states when to use and when not to use, and names the alternative tool.

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