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

Beyond annotations indicating destructiveness, it details exact effects (archive moves, delete recovers, unsubscribe follows RFC 8058), safety thresholds, and domains never touched.

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?

Information is front-loaded and structured by decision type, but slightly dense; bullet points could improve scannability.

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?

Covers main behaviors and constraints well, but omits details on error handling and exact safety threshold values.

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 coverage, the description fully explains account necessity, decision values (archive/delete/unsubscribe), and confirm_token conditions and source.

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 executes tagged decisions with specific actions (archive, delete, unsubscribe), and distinguishes itself as 'THE ONLY DESTRUCTIVE TOOL' among siblings.

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 notes when confirm_token is needed and ties to preview_cleanup, but doesn't explicitly compare to non-destructive siblings like set_decisions or preview_cleanup.

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?

With annotations (readOnlyHint=false) indicating potential side effects, the description fails to clarify if the export modifies any state or where the CSV is stored. It adds minimal context beyond the annotations, leaving behavioral ambiguity.

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 with two sentences, no redundant information, and straightforward structure. Every word adds value to understanding the workflow.

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?

While the description outlines the export-edit-reimport workflow, it lacks details on the CSV output format (beyond the decision column) and parameter semantics. Given no output schema, these gaps reduce completeness.

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 sole parameter 'path' has no description in the schema and the description does not explain what it represents (e.g., local file path, output directory). With 0% schema coverage, the description should compensate but does not.

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 exports all sender groups to a CSV for spreadsheet review, and distinguishes from the sibling import_review_csv by mentioning the re-import step. However, it could be more specific about the CSV's columns beyond the decision column.

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 implies usage for reviewing and editing decisions via the re-import workflow, but does not explicitly state when to use this tool versus alternatives like get_sender_detail or set_decisions. No exclusions or when-not-to-use guidance provided.

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 idempotentHint=true. The description adds value by specifying that the tool 'never returns raw unsubscribe links or a message body' and lists what is included, enhancing behavioral understanding 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 concise at three sentences, front-loading the primary action and efficiently listing contents and exclusions with no redundant 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?

For a simple retrieval tool with three required parameters and no output schema, the description covers output behavior adequately but lacks parameter details, leaving the agent to infer parameter usage from names alone.

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 schema coverage at 0%, the description must compensate but merely mentions 'one exact account/folder/UID reference' without explaining the parameters' meanings, formats, or constraints. This leaves the agent with little guidance for correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'cached headers for one exact account/folder/UID reference.' It lists specific included fields and explicitly states what it never returns, distinguishing it from siblings like get_sender_detail or list_recent_messages.

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

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

The description provides clear context for when to use the tool: retrieving cached headers for a specific message reference. However, it offers no explicit guidance on when not to use it or mentions alternative tools among the siblings.

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 confirm read-only, idempotent, non-destructive behavior. The description adds that it returns both status and result when complete, implying possible polling behavior. However, it does not explain what happens if the job is still running (e.g., returns progressive status) or if the job_id is invalid.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence of 12 words, front-loading the essential action and result without any superfluous content.

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 tool with one parameter and no output schema, the description covers basic purpose but lacks details on behavior during incomplete jobs, error states, or how to interpret results. Annotations partially compensate but the description could be more 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?

The single required parameter 'job_id' has no description in the schema (0% coverage) and the tool description does not explain its format, how to obtain it, or any validation rules. The description adds no value 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 uses the specific verb 'Get' and clearly identifies the resource as 'status and result of one background scan'. It explicitly limits to a single scan job, distinguishing it from list tools like 'list_scan_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?

No guidance is provided on when to use this tool versus alternatives such as 'get_scan_status' or 'list_scan_jobs'. There is no mention of prerequisites, polling frequency, or error handling.

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?

Description adds behavioral context ('from checkpoints', 'without connecting to IMAP') beyond annotations (readOnly, idempotent), clarifying that it shows cached progress rather than live data. 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?

Single sentence, no waste, front-loaded with key action and scope.

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?

No output schema, minimal parameter guidance. Description is adequate for a simple tool but lacks detail on what 'scan progress' entails or output format.

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, description should compensate but does not explain the 'account' parameter's role in filtering per folder, leaving its purpose vague.

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?

Description clearly states the tool shows scan progress per folder from checkpoints and explicitly notes it does not connect to IMAP, which distinguishes it from siblings like get_scan_job and start_scan_job.

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 'without connecting to IMAP' implies a lightweight status check, but no explicit when-to-use or alternative comparisons are provided.

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 agent knows it is safe. The description adds behavioral context about what is returned (e.g., up to 20 sample subjects, folder breakdown). No further behavioral traits (e.g., pagination, rate limits) are disclosed, but the added content detail is valuable beyond 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?

Single sentence that packs the key return components (addresses, folder breakdown, subjects, unsubscribe methods). It is efficient with no wasted words, but could be slightly restructured (e.g., bullet points or separate clauses) for clarity. The most critical info is front-loaded with 'Full detail for one sender domain'.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main return components and mentions the account context. However, it does not explain behavior when account is omitted, nor does it describe the structure of the response (no output schema). Given the lack of output schema, the description should be more explicit about return format and optional parameter effects.

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 compensate. It clarifies that 'domain' is the sender domain and mentions 'for one account', hinting at the optional account parameter. However, it does not explain the account parameter's format, default behavior, or how to specify it. The description adds some meaning but is not fully explicit for both 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 specifies the verb 'get' (implied) and resource 'sender detail', listing concrete items: addresses, folder breakdown, up to 20 sample subjects, and unsubscribe methods. It distinguishes from siblings like list_sender_groups and list_unsubscribe_candidates by focusing on a single domain's full detail.

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 explicit when-to-use or when-not-to-use guidance. The description implies it's for retrieving details of a specific sender domain, but does not mention alternatives (e.g., list_sender_groups for groups) or prerequisites (e.g., domain must exist). Usage context is implied rather than explicit.

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 indicate readOnlyHint=false, so the description's mention of 'import decisions' confirms a write operation. It adds that only specific fields are read, but lacks details on side effects, error handling, or idempotency. The behavioral transparency is adequate but not enriched beyond 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 concise with three front-loaded sentences. Each sentence provides essential information without redundancy or 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?

The description covers purpose, input fields, and a condition, but omits crucial details like whether the import overwrites or appends, error scenarios, and return value. Given the tool's simplicity, the gaps are notable but not severe.

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 one parameter 'path' with no description and 0% coverage. The description does not directly explain the path parameter; it only implies it via the CSV file context. This is minimal added meaning for a critical parameter.

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 imports decisions from a CSV produced by export_review_csv, specifying the verb and resource. It distinguishes itself naturally from the sibling export_review_csv.

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 clear context by referencing export_review_csv as the source and detailing which fields are read. It also gives a conditional rule for the account field. However, it does not explicitly contrast with alternatives like set_decisions or execute_decisions.

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 indicate read-only, open world, idempotent, and non-destructive. The description adds that it connects via IMAP and verifies app passwords, which provides useful behavioral context beyond 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 sentences, no filler, front-loaded with main purpose. Every sentence contributes value.

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 with no parameters and no output schema, the description adequately covers the purpose and a notable side-effect (password verification). Minor gap: no mention of potential latency or caching, but overall sufficient.

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

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

The tool has 0 parameters with 100% schema coverage. The description adds meaning by specifying the output includes folders and message counts, which is helpful beyond the empty 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 explicitly states 'List configured Yahoo accounts with their folders and message counts.' This is a specific verb+resource+scope, and it clearly distinguishes from sibling tools like search_messages or scan_mailbox.

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 implies usage for verifying app passwords ('so this also verifies that the app passwords work'), but does not provide explicit guidance on when to use vs alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as safe. The description adds value by stating it uses cached headers only, never returns bodies or unsubscribe links, and hides sender email by default, all without contradicting 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 two sentences plus a bullet list, front-loaded with the main purpose. Every sentence adds necessary information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 6 parameters and no output schema, the description covers many behavioral aspects (cached headers, hidden sender, no bodies) and includes the prerequisite. Missing details on pagination (limit/offset), sorting, and time filtering (since), but remains fairly complete given the context.

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 description must compensate. It mentions the include_sender_email flag and hints at account/folder filtering via results, but does not explain limit, since, offset, or folder semantics in detail. Some meaning added but insufficient for all 6 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 clearly states the tool lists recently scanned messages using cached headers, specifies the prerequisite (scan_mailbox), and details what is included/excluded. This distinguishes it from siblings like search_messages and get_message_headers.

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 run scan_mailbox first, providing a clear prerequisite. However, it does not compare with alternatives like search_messages or when to use get_message_headers instead, missing explicit exclusions.

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 idempotentHint=true, indicating safe behavior. The description adds little beyond stating the listing action and filtering, but doesn't explain recency ordering or pagination. With annotations covering safety, this is adequate but not enhanced.

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?

One sentence is concise, but omits important parameter details. Could be restructured to include parameter explanations without losing brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of output schema and low parameter coverage, the description leaves significant gaps: no definition of 'recent', no pagination info, no status enumeration. Incomplete for agent understanding.

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

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

Schema description coverage is 0% and the description only mentions 'optionally filtered by status' without explaining the 'limit' parameter or providing possible status values. Fails to compensate for the lack of schema 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 clearly identifies the tool as listing recent background scans with optional status filtering. It distinguishes from sibling tools like get_scan_job (single job) and start_scan_job (initiation), though it doesn't define 'recent' explicitly.

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 this tool versus alternatives such as get_scan_job or get_scan_status. The description lacks context for optimal usage or exclusions.

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. The description adds grouping behavior and filtering details, which is useful 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?

Every sentence adds value: purpose, grouping, account, sort, decision, pagination. No unnecessary words, well-structured.

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?

Covers key aspects but misses min_count parameter and does not describe the return structure beyond 'includes its account'. With 6 parameters and no output schema, more detail would be helpful.

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%, but the description explains sort (enum-like values), decision filter, and pagination. However, min_count parameter is not covered, missing full compensation.

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 lists scanned mail grouped by account and sender domain, which is specific and distinguishes it from sibling list tools like list_accounts or list_recent_messages.

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

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

The description explains parameter usage (account to limit, sort options, decision filter, pagination) but does not explicitly contrast with siblings or provide when-not-to-use guidance.

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

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

Annotations indicate read-only and idempotent behavior. The description adds that raw unsubscribe URLs and sender addresses are never returned, which is a behavioral constraint not covered by annotations. It also clarifies the role of 'execute_decisions' in validation.

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 highly concise, with two short paragraphs. The first paragraph states the purpose, and the second adds necessary detail without redundancy. Every sentence adds value.

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 5 parameters, no output schema, and modest annotations, the description lacks coverage of parameters like sort, limit, offset, and account. It explains the method and key behavioral notes but is not fully complete for an agent to use without additional context.

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 must explain parameters. It only explains the 'method' parameter (all, one_click, mailto, manual). Parameters like sort, limit, offset, and account are not described, leaving significant ambiguity.

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 sender domains with cached unsubscribe methods for one account. It also explains the 'method' parameter values, making the purpose specific. However, it does not explicitly distinguish this tool from siblings like 'execute_decisions'.

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 indicates that validation occurs only during 'execute_decisions', implying this tool is for listing candidates before validation. It provides context on when to use it but lacks explicit alternatives or when-not-to-use guidance.

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

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

Annotations already mark read-only and non-destructive; description confirms nothing is modified and adds detail about confirm_token requirement for large operations.

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, front-loaded with purpose, no wasted words.

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?

No output schema; description mentions counts and confirm_token but not structure. Parameters unexplained. Adequate for a preview tool but incomplete.

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 0% and description does not explain the two parameters (account, decision). Account is only implied by 'one account' but not linked to parameter.

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?

Description clearly states it is a dry run for execute_decisions, providing counts and a confirm_token. Distinguishes from sibling execute_decisions.

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 positioned as a dry run before execute_decisions, implying usage context. No exclusions or alternatives, but clear enough given sibling 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?

The description adds useful behavioral traits (checkpointing, resumption, new mail only after full scan), but it contradicts annotations: readOnlyHint=true while description says it persists data to local database. Per rules, score 1 for 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 well-structured in three paragraphs: purpose, internal behavior, parameter guidance. Each sentence adds value, no fluff. Front-loaded with key action.

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 3 params and no output schema, the description covers purpose, internal mechanics, parameter usage, and default behavior. It lacks error handling or prerequisites but is largely complete. The contradiction slightly detracts.

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 description carries burden. It explains 'folders' allows specific folder selection, 'max_messages' caps the run, and 'account' is required. This adds meaning beyond the schema's basic types and defaults.

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 scans Yahoo account folders, pulling header-level data only. It specifies the resource (Yahoo account folders), action (scan), and scope (header-level). This distinguishes it from sibling tools like get_message_headers or triage_new_mail.

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 when to use (default scans all except Trash/Drafts/Sent, can limit folders or max_messages) and mentions checkpointing for resumption. However, it does not explicitly compare to similar tools like start_scan_job or get_scan_status, leaving some ambiguity.

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, indicating safety. The description adds valuable behavioral context: results never expose raw unsubscribe URLs or message bodies, and the search operates on cached headers. This exceeds annotation coverage and provides critical privacy/security assurances.

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 three sentences with no wasted words. It front-loads the core purpose, then explains query behavior, and finally lists filters and result limitations. Every sentence adds value.

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 no output schema and 15 parameters, the description is reasonably complete but lacks details about the return format (e.g., which header fields are included) and pagination behavior (limit/offset). The result limitation is mentioned, but for a search tool, more context on output structure would be beneficial.

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 compensate. It explains that the free-text query matches subject, sender domain, and sender email, and lists additional exact filters (account, folder, sender, date, unsubscribe, decision) which map to several parameters. However, it does not explain parameters like sort, limit, offset, include_sender_email, exclude_stale, or subject_contains, leaving gaps.

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 cached message headers without connecting to IMAP, which distinguishes it from potentially similar tools that require IMAP connectivity. The verb 'search' and resource 'cached message headers' are specific and unambiguous.

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

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

The description provides clear context for when to use this tool (for offline, cached search) by stating 'without connecting to IMAP'. However, it does not explicitly state when not to use it or mention alternative sibling tools, though the context helps inform decision-making.

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

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

Beyond the minimal annotations (readOnlyHint=false, destructiveHint=false), the description clarifies it does not modify Yahoo Mail and explains account inference. This adds useful behavioral context.

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 succinct sentences: purpose, entry format, and account behavior. No redundant 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?

The description covers the entry format and account handling thoroughly. It does not mention return values or error behavior, but given the batch nature, this is adequate.

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

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

With 0% schema description coverage, the description fully compensates by detailing the entry format, including the decision enum and optional fields. It also explains the account parameter's behavior.

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 batches cleanup decisions for sender domains. It distinguishes from siblings like 'execute_decisions' (which likely executes decisions) and 'preview_cleanup'.

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

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

The description explains account handling and explicitly states the tool never modifies Yahoo Mail, providing helpful context. However, it does not explicitly contrast with siblings or state when not to use it.

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: durability, background execution, immediate return, and resumption from checkpoints after server restart. This enriches the agent's understanding beyond the annotations without 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 with three focused sentences. The first sentence states the core action, the second provides usage guidance, and the third explains post-invocation behavior and resilience. No unnecessary words.

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 (3 parameters, no output schema), the description explains the overall workflow and resilience but omits details about parameter semantics, response format, and error scenarios. It is adequate for basic understanding but incomplete for full autonomous use.

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

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

Schema description coverage is 0%, and the description does not explain any of the three parameters (account, folders, max_messages). It fails to add meaning beyond the schema structure, leaving the agent without guidance on parameter usage or constraints.

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 'Start a durable background header scan and return immediately', specifying the verb (start) and resource (background header scan). It distinguishes from sibling tools like scan_mailbox by emphasizing that it returns immediately and runs in the background, making it clear for async use cases.

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 says 'Use this for large scans from remote clients that impose request timeouts', providing a clear use case. It also advises polling with get_scan_job. While it doesn't state when not to use it (e.g., for small synchronous scans), the guidance is specific and helpful.

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 details beyond annotations: it discloses incremental scanning, emphasizes it never deletes/unsubscribes (consistent with readOnlyHint and destructiveHint), and explains the three return groups. However, it does not clarify how 'last scan' is determined or behavior on first run.

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 (three sentences plus a bullet-like list) with no wasted words. It front-loads the purpose, then provides negative constraints, and finally details output structure.

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?

While the description covers the tool's purpose and return format adequately, it lacks explanation of parameters and operational details like how 'last scan' is tracked per account or folder. An output schema would further help, but missing parameter semantics is a notable gap.

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 description makes no mention of the parameters (account, folders), despite 0% schema coverage. The agent must infer parameter use from names alone, missing critical context like the behavior of the optional folders parameter.

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 purpose with a specific verb ('triage'), resource ('new mail'), and scope ('since the last scan, incremental'). It lists three distinct return categories (suggestions, new_senders, attention) and explicitly says what it does not do (delete/unsubscribe), making differentiation from siblings like scan_mailbox or start_scan_job implicit.

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 does not provide explicit guidance on when to use this tool versus alternatives like scan_mailbox or start_scan_job. It implies incremental use but offers no context for selecting this tool over others.

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