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

No annotations are provided, so the description carries the burden, and it does reasonably well: it discloses the two verification scopes (IMAP only by default, SMTP optionally), the all-accounts case, and the return shape (ok/stage/error/hint). It omits side-effect/auth-persistence details, but for a non-mutating credential check this is solid coverage.

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

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

Front-loaded one-line purpose followed by short Args and Returns blocks; every line carries information. The Returns block mildly duplicates the output schema, which is the only wasted space.

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 two-parameter, output-schema-backed preflight check, the description covers scope, defaults, and result structure adequately. Failure semantics (what 'stage' values mean) are left to the output schema, which is acceptable.

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 must carry both parameters, and it does: 'account' is defined as an accounts.json key with None meaning check-all, and 'check_smtp' is defined as also verifying SMTP with a stated IMAP-only default. Nothing needed to call the tool is missing.

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: verify IMAP login (optionally SMTP) for one or all accounts. The 'Preflight' framing immediately separates it from all sibling mail-operation 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?

'Preflight' clearly signals this should be run before other mail operations, and 'check all' vs single-account behavior is stated. It does not explicitly name alternatives or state when not to call it, but the context is unambiguous.

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 no annotations the description carries the full burden. It usefully discloses two defaults ('subscribe' defaults True and its client-visibility effect; account falls back to the file-marked default), but is silent on duplicate-name handling, required permissions/auth, error behavior, and idempotency for a mutation tool.

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

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

The purpose sentence is front-loaded and the per-argument notes are scoped tightly to one field each. It is slightly verbose with the multi-line separator explanation, but no sentence is wasted.

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

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

An output schema exists, so return-value detail is not required, and all three parameters are covered. The remaining gap is behavioral: duplicate handling and auth/permission expectations are unstated, which matters more given the absence of annotations on a create operation.

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, and it does: 'name' gets nested-folder separator guidance with concrete examples, 'subscribe' explains its default and effect, and 'account' explains the key source and default behavior. This is genuinely additive, though 'account' formatting could be tightened.

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 ('Create a new mailbox folder'), which is unambiguous and clearly distinct from read-oriented siblings like yahoo_list_folders or destructive ones like yahoo_empty_folder. It does not, however, explicitly name a sibling or contrast scope, so it stops short of 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 when-to-use guidance: nothing tells the agent to check existing folders first via yahoo_list_folders, or how this relates to yahoo_empty_folder. The Args block describes inputs but never states conditions or alternatives, leaving routing entirely to inference.

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 no annotations present, the description carries the full burden and does so well: it discloses that the default is a reversible move to Trash, that permanent=true performs \Deleted + expunge in place and is IRREVERSIBLE, and it flags that ranges/lists are refused. That is exactly the safety context annotations would otherwise supply.

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 one-line summary is front-loaded with the destructive-mode default before any argument detail, and each Args line adds distinct information with no repetition of the schema's titles.

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

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

An output schema exists so return values needn't be described; with the destructive-path behavior, account resolution rule, and parameter constraints all covered, an agent has everything needed to call this mutation 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 description coverage is 0%, so the description must compensate for all four parameters — and it does, giving each a meaning, a default, and for msg_id a provenance note plus an explicit constraint ('one UID, ranges and lists are refused') that the schema does not convey.

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 ('Delete a single message, addressed by UID') and scopes it to exactly one message, which separates it from siblings like yahoo_empty_folder and yahoo_move_mail without opening their schemas.

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

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

Explicitly contrasts the two modes (default move-to-Trash vs permanent expunge) and tells the caller where msg_id comes from (yahoo_list_mail / yahoo_search_mail), but it never names an alternative tool for related intents such as moving rather than deleting.

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 no annotations, the description carries the burden and does disclose meaningful behavior: a filesystem write with a hard security constraint (allowed directories, refusal of anything else, YAHOO_MAIL_ALLOWED_DIRS override) and default account resolution from accounts.json. It omits overwrite behavior, what happens when no attachments match, and any size/rate limits.

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

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

Front-loaded purpose sentence followed by structured Args entries; each line adds real meaning. The out_dir entry is the longest but its length is justified by the security constraint it conveys.

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

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

An output schema exists, so return-value explanation is unnecessary, and the description covers the risky parts (write target restrictions, account selection, filtering). Minor gaps remain around the no-match/no-attachment case and error behavior, but an agent has what it needs to invoke it 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 description coverage is 0% (all 5 params undocumented in the schema), yet the description documents every one: msg_id provenance, folder default INBOX, out_dir default plus the security restriction, filename_filter as a case-insensitive substring match, and account key/default semantics.

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 (download) and resource (attachments from a message) with the destination (to disk). No sibling tool overlaps this action, so an agent can identify it unambiguously from the name and first sentence.

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 tells the agent where msg_id comes from (yahoo_list_mail / yahoo_search_mail), which is useful routing context, but gives no explicit when-to-use/when-not guidance or alternatives for retrieving attachments versus other mail operations.

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 no annotations, the description carries the full burden and does so well: it discloses the destructive mechanism, irreversibility, and the critical default-safe behavior (confirm=False returns a would-purge count and deletes nothing). This is exactly the behavioral context an agent needs before invoking a destructive tool.

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

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

Front-loaded with the destructive action and safety note, then a well-organized Args block. The Args section partly restates schema field names, but since schema coverage is 0% that repetition is load-bearing rather than wasteful; a slightly leaner phrasing would be marginally better.

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

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

An output schema exists, so return values needn't be spelled out, and the description still explains the meaningful return case (the dry-run count). Combined with full parameter and safety coverage for a destructive 3-param tool, nothing an agent needs is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it documents all three parameters: folder with examples, confirm with its default/dry-run semantics, and account with its source (accounts.json) and default resolution. No parameter is left ambiguous.

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 ('PERMANENTLY delete ALL messages in a folder') plus the underlying mechanism (mark \Deleted + EXPUNGE), which no sibling describes. An agent can distinguish it from yahoo_delete_mail or yahoo_move_mail from the description alone.

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 scopes intended targets ('Intended for Bulk (spam) and Trash') and flags irreversibility, giving clear when-to-use context. It does not name an alternative tool (e.g. yahoo_delete_mail) or state when NOT to use this versus a selective delete, so it falls 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?

With no annotations present, the description carries the full burden and does reasonably well: it discloses the critical draft-vs-send behavior (send_now default False saves to Drafts), the default source folder, the default account resolution (accounts.json), and that additional_text is plain text prepended above forwarded content. It omits auth requirements, rate limits, and whether the source message is modified.

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

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

The purpose is front-loaded in one sentence, followed by a clean per-argument list. It is slightly padded by the 'Returns' line, which duplicates the existing output schema, but overall it is tight and easy to scan.

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 an 8-parameter mutation tool with no annotations, the description covers every argument's meaning and defaults, plus the draft/send behavioral split. Because an output schema exists, the return-value sentence is a minor bonus rather than a necessity, and nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it does for all 8 parameters: msg_id provenance, comma-separated recipient syntax, cc/bcc roles, additional_text format and placement, folder default, send_now semantics, and the account key format with its default. This fully closes the schema gap.

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 ('Forward an existing message'), plus a distinguishing trait ('preserving attachments'). This separates it from the sibling yahoo_send_mail, which composes a new message rather than forwarding an existing one.

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 usage by tracing msg_id back to yahoo_list_mail / yahoo_search_mail and by explaining that send_now=False yields a draft rather than a dispatch. However, it never explicitly says when to choose this over yahoo_send_mail or what prerequisites (auth via yahoo_check_auth) are needed.

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 no annotations, the description must carry the behavioral burden, and 'Read' does signal a non-mutating operation. It also documents useful defaults (folder=INBOX, body=text, max_body_chars=5000) and the truncation behavior. However, it says nothing about auth/permission requirements, rate limits, or what happens when a UID is absent.

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

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

The purpose is front-loaded in the first line, followed by a compact args list where each entry earns its place. The structure is clean and proportionate to a 5-parameter tool, with no 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?

An output schema exists, so return formatting need not be described, and the description fully documents inputs. What remains thin is behavioral context (permissions, error/edge behavior) for a tool with zero annotation coverage, but for a simple read operation the definition is largely 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?

Schema description coverage is 0%, so the description is the only source of parameter meaning, and it covers all five parameters: msg_id provenance, folder default, body format options (text/html/none), truncation limit, and the account key from accounts.json with its default. This meaningfully exceeds the bare schema and enables 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?

States a specific verb and resource ('Read a specific message by UID') and ties it directly to the sibling tools that produce the UID ('the "id" from yahoo_list_mail or yahoo_search_mail'). An agent can distinguish this fetch-by-id tool from the list/search siblings 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?

The description clearly establishes the workflow context by stating the msg_id comes from yahoo_list_mail or yahoo_search_mail, implying this tool is used after a listing/search step. It does not, however, state explicit exclusions or alternatives (e.g., when to prefer search over this).

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 no annotations, the description carries the full burden of behavioral disclosure. It adds useful context by stating that it returns folder names and explains the account default behavior, but it omits any authentication requirements, rate limits, or error behavior. A read-only listing is low-risk, but the absence of annotations leaves gaps.

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 purpose, but the second sentence ('Returns folder names available in the Yahoo mailbox') largely repeats the first sentence. Since an output schema exists, this return-value sentence may not earn its place, creating 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 simple list tool with one optional parameter and an output schema, the description covers purpose and parameter behavior adequately. It does not address authentication, but the low complexity and presence of an output schema make the definition largely 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 description coverage is 0% for the single optional account parameter, so the description must compensate. It does so effectively by explaining that account="<key>" refers to another account in accounts.json, and that omitting it uses the default account marked in that file. This fully clarifies the parameter's semantics beyond what the schema provides.

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

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

The description states a specific verb and resource: 'List all mailbox folders.' This clearly distinguishes the tool from mail-related siblings like yahoo_list_mail and yahoo_get_mail. However, it does not explicitly differentiate itself from other folder-related siblings such as yahoo_create_folder or yahoo_empty_folder.

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 no guidance on when to use this tool versus alternatives. The only usage instruction concerns the account parameter, not tool selection. There is no mention of prerequisites or conditions under which folder listing is appropriate.

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 no annotations, the description carries the full burden, and it delivers real behavioral context: the effective default of last 30 days when no date is given (schema only shows null), default folder INBOX, max 100 results, and account resolution from accounts.json. What it omits is the safety profile (that this is a non-mutating read) and any error/auth failure behavior.

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

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

Front-loaded with the one-line purpose, followed by the non-obvious id/IMAP-UID note, then a compact Args block. Every sentence carries information the agent cannot get from the schema, and there is no repetition or 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?

An output schema exists, so return-value detail is not required, and all parameters are documented. The main remaining gap is that pagination beyond a single top-window, auth requirements, and behavior on invalid folder/date are unspecified for a 4-parameter listing tool with 12 siblings.

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 and it does: it documents all four parameters with types, defaults (top=20, folder=INBOX, account=file default), the YYYY-MM-DD date format for 'since', the max of 100, and the meaning of the account key. This goes well beyond the bare titles and defaults in 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 with scope: 'List recent messages' with the fields returned (subject, sender, date, attachment indicators). It is clear what the tool does, but it never positions itself against siblings like yahoo_search_mail or yahoo_get_mail, so the agent must infer the boundary between browsing recent mail and querying it.

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

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

Usage is implied by the default 'last 30 days' window and by the note that the returned id is what 'every msg_id parameter expects', which hints at the browse-then-act workflow with get_mail/move_mail/delete_mail. However, there is no explicit when-to-use versus when-not, and no mention of search_mail as the alternative for targeted queries.

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?

No annotations are provided, so the description carries the burden. It implies a safe read-only count operation and discloses defaulting behavior (folder defaults to INBOX, account defaults to the one marked default), but never explicitly states it is read-only, requires auth, or what the output shape is.

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 front-loaded summary sentence followed by a compact Args block; every line is useful. Slightly loose as a prose description but appropriately sized for a 2-parameter tool.

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 an output schema present, return values need not be spelled out, and the description already names the three stat categories. Both parameters are documented, so the only real gap is the absence of explicit read-only/auth confirmation for a tool with zero annotations.

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, and it does: it defines folder as the mailbox folder with the INBOX default and account as an accounts.json key with examples ('personal', 'work') plus the default rule. That adds real meaning the schema lacks, though formats/valid values remain loose.

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 (mailbox statistics) and enumerates what is returned: total messages, recent/unseen counts, date range. This clearly separates it from yahoo_list_mail and yahoo_search_mail, though it never explicitly names a sibling.

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 word 'Quick' and the stats framing imply this is the lightweight summary tool rather than a message-listing tool, but there is no explicit when-to-use vs when-not guidance or named alternative among the many sibling mail tools.

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

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

With no annotations, the description carries the full burden, and it does so well: it discloses the server-dependent execution path (UID MOVE, else UID COPY + \Deleted + UID EXPUNGE, else bare EXPUNGE), which is real behavioral context an agent cannot infer. It omits auth/permission requirements and does not say the source message is removed, but the mechanism disclosure is unusually rich.

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

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

Front-loads the action, then the mechanism, then prerequisites, then an Args block. Every sentence earns its place, though the multi-line protocol explanation is dense enough to be slightly heavy for a single-field move.

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

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

Output schema exists, so return values need not be explained. Prerequisites, parameter semantics, and the fallback mechanism are covered; only auth/permission expectations are left unstated, which is a minor gap for a mutation tool with no annotations.

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 must compensate, and it documents all four parameters: msg_id as a single UID with ranges/lists refused, dest_folder as target name, source_folder defaulting to INBOX, and account as an accounts.json key with a default. This adds meaning well beyond the bare schema titles.

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 ('Move one message') plus the addressing scheme ('addressed by UID') and source/destination folders. An agent can distinguish this from yahoo_delete_mail, yahoo_empty_folder, or yahoo_list_mail 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?

Gives prerequisites clearly: the destination folder must already exist and yahoo_create_folder should be used first if needed, and it points to yahoo_list_mail / yahoo_search_mail as the source of the UID. It does not state when another tool (e.g. delete or copy) is preferred, so it stops just short of full when-not 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that result IDs are IMAP UIDs matching yahoo_list_mail's output, which is context beyond the schema. But it does not state that the operation is read-only, nor does it mention authentication requirements, rate limits, or side effects.

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 purpose, then a useful return-ID note, then a well-structured Args list. Every item is necessary given the 0% schema description coverage, and there is no redundant 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?

For a six-parameter search tool with no annotations but an output schema, the description covers purpose, all input semantics, defaults, and the key return-value identifier. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does so thoroughly. Every one of the six parameters is documented with meaning, allowed values or formats, and defaults: query is case-insensitive, folder defaults to INBOX, field accepts subject/from/body/all, since uses YYYY-MM-DD, top defaults to 20, and account is an accounts.json key.

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

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

The description states a specific verb and resource: 'Search messages by keyword in subject, sender, or body.' It also notes that result IDs are IMAP UIDs matching yahoo_list_mail, which aids cross-referencing. However, it does not explicitly distinguish this tool from siblings like yahoo_list_mail or yahoo_get_mail beyond the implicit search-vs-list difference.

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 guidance is given about when to use this tool versus alternatives such as yahoo_list_mail or yahoo_get_mail. The description only states the operation and its arguments, leaving the agent to infer that this is the keyword-search 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?

With no annotations, the description carries the full burden and does so well: it explains that send_now=False saves to Drafts, that attachments must sit in allowed folders (default ~/Downloads or temp, overridable via YAHOO_MAIL_ALLOWED_DIRS) or the operation fails, and that account defaults to the file-marked default. It stops short of covering auth/permission prerequisites or rate limits.

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?

Format is well front-loaded: a one-line purpose followed by an Args list, so the key behavior precedes the detail. The per-argument lines are mostly single clauses that earn their place, though the attachments note is comparatively verbose.

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 nine-parameter mutation tool with no annotations, the description covers the critical behavioral facts (draft-vs-send default, attachment folder constraint, account default), and an output schema exists so return-shape explanation is not required. It is largely sufficient, with only prerequisite/error semantics beyond attachments lightly covered.

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, and its Args block documents all nine parameters including format hints ('comma-separated'), the html flag semantics, allowed attachment directories, and the account key convention. This adds meaning well beyond the bare schema 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?

States a specific verb and resource ('Send a new email via SMTP, or save as draft') and immediately flags the default behavior of saving a draft. This cleanly distinguishes it from siblings like yahoo_forward_mail and yahoo_move_mail, so an agent can identify it 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?

The dual mode (send vs draft) is implied through the send_now default, giving some sense of when each path applies. However, it never names alternatives such as yahoo_forward_mail or states when-not to use this tool, so usage guidance remains inferred rather than explicit.

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