Zoho Mail MCP

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write-but-safe profile is partly covered. The description adds real behavioral context beyond that: the destination (Archive folder), the caveat 'on most accounts', and the implication that the action is reversible via move.

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

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

Two tight sentences with the core action front-loaded, followed by the reversal path and then the parameter rule. Every clause earns its place and nothing is padded.

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

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

For a two-parameter mutation with no output schema, the description covers the action, its effect, the reversal path, and the parameter selection rule. It leaves the return shape implicit, but with no output schema declared that is a minor omission.

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?

Property-level schema coverage is effectively zero despite the item-level notes, so the description carries the semantic load. It explains that messageId targets an individual email, threadId targets a whole conversation, and that exactly one of the two must be supplied — a real constraint the schema conveys only via additionalProperties and minItems.

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 ('Archive emails') with the observable effect ('moves them to the Archive folder'). It distinguishes itself from sibling zoho_move_emails by naming it explicitly as the reversal path, so an agent can route between the two.

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 names the alternative (zoho_move_emails) and the condition that calls for it (moving archived mail back), which clarifies when this tool is the right pick versus a move. It does not contrast against delete, spam, or label operations, so it stops short of full when/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?

Annotations already declare destructiveHint=true, but the description adds the crucial nuance that the DEFAULT is recoverable (moved to Trash) and that permanent deletion is gated behind a server flag. This reversibility and prerequisite information materially changes how an agent should treat the call and is not derivable from annotations 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?

Three short sentences with zero padding; the default behavior is front-loaded before the opt-in destructive path. Every sentence carries information an agent needs.

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 3-parameter mutation tool with no output schema and full schema coverage, the description covers the essential behavioral contract: default recoverability, the permanent-delete flag, and its environment prerequisite. It could note the failure mode when expunge is requested without the server flag, but the 'only works when' phrasing already implies it.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema's terse 'Permanently delete instead of moving to Trash' by disclosing that expunge only functions when the server runs with ZOHO_ALLOW_PERMANENT_DELETE=true, a runtime precondition the schema does not mention.

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 an email') and immediately scopes the operation by distinguishing soft delete (Trash, recoverable) from permanent delete. This differentiates it from siblings like zoho_move_emails and zoho_archive_emails without the agent needing to open another 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 explains the two modes of this tool, but gives no explicit guidance on when to choose deletion over alternatives such as zoho_archive_emails or zoho_move_emails. Usage is implied by the tool name rather than stated, leaving the routing decision 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 readOnlyHint=false, the description usefully discloses the actual side effect (a file is written to local disk) and the return value (the saved path), which matters given there is no output schema. It does not mention overwrite behavior or failure/error cases, so it is good but not exhaustive.

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 short sentences, front-loaded with the action and effect, then the prerequisite. No filler; every clause earns its place.

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

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

For a five-parameter download tool with no output schema, the definition covers purpose, side effect, return value, and where to obtain IDs. Remaining gaps (overwrite semantics, error behavior, and the default saveTo path already in the schema) are minor.

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

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

Schema coverage is 100%, so the baseline would be 3; however, the description adds provenance meaning by stating that attachmentId and fileName come from zoho_get_attachment_info, saving the agent a discovery step. It leaves the other parameters (folderId, messageId, saveTo) entirely to 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+resource+effect: 'Download an email attachment to the local disk and return the saved path.' This distinguishes it from the metadata-only sibling zoho_get_attachment_info and from zoho_download_inline_image, which is confirmed by the second sentence routing the agent to zoho_get_attachment_info for IDs.

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

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

Gives clear prerequisite guidance by naming zoho_get_attachment_info as the source of attachmentId and the file name, which tells the agent where this tool sits in the workflow. It stops short of explicit when-not-to-use conditions or contrasting it with zoho_upload_attachment/zoho_download_inline_image, so it does not reach a 5.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, and the phrase 'to the local disk' is consistent with writing a file locally, so there is no contradiction. Beyond that, the description adds little: no mention of overwrite behavior, error handling if contentId is not an inline image, or permission needs. With annotations covering the safety profile, a 3 is appropriate.

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

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

Two tight sentences with the action and destination front-loaded and the parameter hint second. Every clause carries information; nothing is padded or repeated.

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 file-download tool with no output schema, the description covers what it does, where it writes, and how to obtain the non-obvious contentId. Remaining gaps (overwrite/error behavior, whether it also writes to the server mailbox) are minor but not fully addressed.

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 80% and the schema documents saveTo's default path, fileName, folderId, and messageId. The description adds value for the one undocumented parameter (contentId), explaining it is the cid returned by zoho_get_attachment_info — meaning beyond what the bare 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?

States a specific verb and resource ('Download an inline image of an email') and adds the destination ('to the local disk'). This implicitly distinguishes it from the sibling zoho_download_attachment (normal attachment) and zoho_get_attachment_info, but it never names those siblings explicitly, so the differentiation is left to inference.

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?

Points the agent to the prerequisite tool and required flag: contentId comes from zoho_get_attachment_info with includeInline=true. That is clear usage context, but there is no explicit 'use this instead of X' routing or any 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description's "set or clear" correctly reflects the mutation-though-non-destructive nature, but adds nothing about permissions, idempotency, or what clearing a flag affects.

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 tightly written sentences with the verb front-loaded and the targeting constraint immediately following. No filler, nothing 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?

For a 6-parameter mutation tool with no output schema, the description covers targeting but leaves the folder-related parameters, the archive case, and the overlap with zoho_flag_threads unexplained. Adequate but with clear 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 coverage is only 50%, so the description should carry more weight. It usefully documents the messageId/threadId mutual exclusivity that the schema does not enforce, but says nothing about folderId, isArchive, or isFolderSpecific beyond what the schema already 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?

States a specific verb pair (set/clear) and resource (flag on emails), and distinguishes the two targeting modes. However it doesn't acknowledge the sibling zoho_flag_threads, which also flags threads, leaving some ambiguity about which tool owns the thread case.

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 parenthetical "give one of the two" gives implied usage guidance for messageId vs threadId, which is genuinely useful. But there is no when-to-use versus zoho_flag_threads or zoho_archive_emails, and no statement of prerequisites 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=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds only the word 'clear' (implying reversibility) and the thread-level scope; it says nothing about idempotency, permission needs, or what clearing does to mixed-flag threads.

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

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

A single tight sentence with the action front-loaded and zero filler. It is arguably under-specified rather than over-long, but nothing in it 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?

For a 5-parameter mutation tool with no output schema and 60% schema coverage, the description should at minimum explain the flag options and the folder/archive scoping flags. Most of what an agent needs to call this correctly is absent from the description and only partially covered by the schema.

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

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

Schema description coverage is 60%, and the description contributes nothing parameter-specific: it never mentions the flag enum values (info/important/followup), folderId, isArchive, or isFolderSpecific. Only the enum name 'flag_not_set' plus 'set or clear' hints at the clear semantics, leaving several documented-in-name-only fields unclarified.

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 pair ('Set or clear') and an explicit resource scope ('whole threads'), which implicitly separates it from the sibling zoho_flag_emails that acts on individual emails. It does not name that sibling outright, so sibling differentiation is inferential rather than explicit.

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, no prerequisite (e.g. folder/scoping requirements), and no mention of the alternative zoho_flag_emails or other thread operations. The agent is left to infer that 'threads' vs 'emails' is the selection criterion purely from the tool name.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds the non-obvious defaulting behavior when accountId is omitted, which is real added value, but it says nothing about what 'details' are returned or what happens for an invalid/unknown account.

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 short sentences, no filler, with the core purpose front-loaded and the default behavior following immediately. Every word earns its place.

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

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

For a simple single-account getter with annotations covering safety, this is nearly complete. The only gap is that no output schema exists and the description never indicates what account details are returned, but that is a minor omission for a read-only tool.

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

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

Schema coverage is 100% and the schema already explains the string/64-bit ID caveat. The description supplements this by clarifying that accountId is genuinely optional via 'Defaults to the configured account', which resolves the optionality implied by a non-required 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?

States a specific verb and resource ('Get details of one mail account'), clearly a single-account read, which contrasts implicitly with the sibling zoho_get_accounts (plural list). It does not name that sibling explicitly, so the differentiation is inferential rather than stated.

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

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

'Defaults to the configured account' tells the agent the tool works without an ID, which is useful context for choosing it. However, there is no explicit guidance on when to use this versus zoho_get_accounts or any 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 openWorldHint=true, so the safe-read profile is covered. The description adds useful detail by listing the response fields, but says nothing about auth scope, rate limits, or the relationship to the singular-account variant.

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

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

A single well-formed sentence with the resource front-loaded and the returned fields parenthesized. It is appropriately sized, though slightly terse given the sibling ambiguity it leaves unresolved.

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 parameters and no output schema, the description compensates by enumerating the return fields, which is genuinely useful. The one missing piece is disambiguating this from zoho_get_account, but otherwise it is complete enough to call 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 tool takes zero parameters, so the schema carries no semantic burden and the baseline is 4. The description correctly implies no filtering inputs are needed.

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 ('Get all mail accounts of the authenticated user') and enumerates the returned fields. It is clear what the tool does, but it never distinguishes itself from the sibling zoho_get_account, so an agent can't tell the plural from the singular without guessing.

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

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

There is no statement of when to use this tool, no exclusions, and no mention of the near-identical zoho_get_account sibling. An agent must infer usage purely from the name.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that inline images and their cid can be surfaced on request, but says nothing about pagination, ordering, or behavior when no attachments exist.

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 sentence with the resource first and the optional behavior trailing; no filler. Arguably a touch dense with the parenthetical field list, but every clause carries information.

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

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

For a read-only tool with no output schema, naming the returned fields is the key completeness requirement, and that is done. Only minor gaps (ordering, empty-result behavior) remain, which matter little for an info-listing call.

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 documents folderId and messageId (including the string-precision caveat), and the description supplies the missing semantics for includeInline by explaining it pulls in inline images with their cid. That closes the 67% coverage gap with real meaning added 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?

Specific verb (List) plus resource (attachments of an email), and it even enumerates the returned fields (attachmentId, attachmentName, attachmentSize). It is clearly separable from sibling download_attachment or get_email_content, though it doesn't name those siblings 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 vs neighbors like zoho_get_email_metadata, zoho_get_email_content, or zoho_download_attachment. The purpose implies the use case, but no prerequisites or alternatives are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds that the returned payload is the HTML body (helpful since there is no output schema), but says nothing about the format of surrounding structure, whether attachments/quotes are dropped, or how includeBlockContent changes output.

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

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

A single front-loaded sentence with no filler; it is efficient and readable. It is arguably too thin for a tool with three parameters, but nothing in it 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?

With no output schema, the description should carry more of the return-value burden; stating 'body (HTML)' is the minimum. It omits any note on authentication, error conditions, or how the required folderId/messageId pair is obtained, leaving substantial context to the schema.

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

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

Schema description coverage is 100% and the schema itself explains string-encoded 64-bit IDs and the includeBlockContent flag, so the baseline is 3. The description contributes nothing beyond 'body (HTML)' and does not clarify interactions between the 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 states a specific verb and resource ('Get the body (HTML) of an email'), and the parenthetical '(HTML)' usefully distinguishes it from header/metadata siblings. However it never names the closely related tools (zoho_get_email_metadata, zoho_get_email_headers, zoho_get_original_message), so an agent must infer the boundary itself.

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

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

There is no guidance on when to call this versus fetching metadata, headers, or the original message, and no stated prerequisites (e.g. needing a folderId from zoho_list_folders). The only hint of usage context lives in the schema, not the description.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the concrete header payload (Message-ID, References, Received, authentication results), which gives useful context, but says nothing about failure modes, missing headers, or the raw/parsed behavioral difference.

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

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

A single front-loaded sentence with zero filler; the parenthetical enumeration earns its place by telling the agent what comes back. It is arguably a touch thin for a tool with no output schema, but nothing 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?

With no output schema, the description compensates by naming the fields returned, which is the key missing piece. It omits any note on when headers are unavailable or how raw=true/false changes the payload, but for a simple read tool this is close to 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 100%, so folderId, messageId and raw are already fully documented by the schema, including the 64-bit precision caveat. The description adds no parameter meaning beyond that, which is the baseline expectation.

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 ('Get the internet message headers of an email') and enumerates the header types returned, so an agent knows exactly what this returns. It does not, however, differentiate itself from close siblings like zoho_get_email_metadata or zoho_get_original_message, which likely also expose header-adjacent data.

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, no prerequisites, and no mention of alternatives such as zoho_get_email_metadata or zoho_get_email_content. The listed header names hint at diagnostic/authentication uses, but the agent must infer that entirely.

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=true, so the safety profile is covered by structured data. In the absence of an output schema, the description's enumeration of returned fields adds genuine transparency about what comes back, but it says nothing about auth, rate limits, or failure behavior for a non-existent/inaccessible message.

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

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

A single front-loaded sentence naming the operation before the field list; zero filler. The parenthetical list is dense but every item is informative, so it earns its length.

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 two-required-param read tool, this is nearly complete: the safety annotation covers the read semantics, the schema fully documents the inputs, and the description compensates for the missing output schema by listing the returned fields. Only the sibling boundary (metadata vs headers vs content) remains unaddressed.

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

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

Schema description coverage is 100% and the schema already documents both folderId and messageId thoroughly, including the string-precision warning and the source tools for each ID. The description adds no parameter-level detail, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ("Get metadata of an email") and enumerates exactly which fields are returned (subject, sender, recipients, times, size, status, flag, attachment flags, summary). This is clear, but it never explicitly distinguishes itself from adjacent siblings like zoho_get_email_headers, zoho_get_email_content, or zoho_get_original_message, leaving the agent to infer the boundary from the field list 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?

No when-to-use or when-not-to-use guidance is given, and no alternative tool is named. The agent must infer that this is the lightweight metadata lookup versus content/header siblings purely from the enumerated fields, with no explicit routing statement.

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=true, so the safety profile is covered. The description adds nothing beyond that — it does not say what "details" are returned, how missing/permission-denied folders behave, or that this is a non-mutating lookup.

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

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

A single short sentence with no filler and the resource front-loaded. It is efficient, but its brevity reflects under-specification rather than disciplined conciseness.

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 read tool with annotations covering safety and a fully documented schema, the definition is minimally adequate. It leaves vague what "details" actually comprises, which matters since there is no output schema to fall back on.

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

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

Schema description coverage is 100% and the folderId entry already documents the pattern and the 64-bit string caveat plus its source (zoho_list_folders). The description contributes no additional parameter meaning, so the baseline of 3 applies.

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

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

The description states a clear verb and resource ("Get details of a single folder"), and the word "single" hints at the single-vs-list distinction. However, it never names zoho_list_folders, so an agent must infer the boundary from the sibling list 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?

There is no guidance on when to use this tool versus zoho_list_folders or the other retrieval tools, and no stated prerequisites. The only routing signal is the ambiguous word "single".

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=true, so the safety profile is covered. The description adds a genuinely useful behavioral detail: the return is the full raw MIME source rather than parsed fields. It does not mention size limits, binary/attachment handling, or encoding, which are relevant for a MIME dump.

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, front-loaded with the verb and resource, with the scope clarification packed into a parenthetical. No filler or 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 single-parameter read tool with full schema coverage and annotations, the description is nearly sufficient, and its scope note partially compensates for the absent output schema by stating what the payload contains. It stops short of addressing practical concerns like large messages or attachment parts.

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

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

Schema coverage is 100% and the single messageId parameter is thoroughly documented in the schema (string, pattern, precision warning, source of the ID). The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('original MIME source of an email') with a clarifying parenthetical that scopes the output to 'headers + all parts'. This implicitly separates it from the headers-only and body-only siblings, but it never names those siblings explicitly, so it falls short of full differentiation.

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 no when-to-use guidance, no prerequisites, and no alternative tool to choose instead. An agent must infer that raw MIME is wanted rather than the parsed content from zoho_get_email_content or zoho_get_email_headers; nothing in the text tells it which to pick.

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 this a read-only, open-world operation, so the safety profile is covered. The description adds genuine context beyond that: the default ordering (newest first), the cross-folder behavior when folderId is omitted, and the full set of returned fields in the absence of an output schema.

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

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

Two compact sentences, with the scoping/ordering rule front-loaded and the return-field list following. The field enumeration is justified because no output schema exists, though it is a long untokenized run of field names.

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 16-parameter list tool with no output schema, the description usefully compensates by naming returned fields and stating default ordering and folder scope. It stops short of explaining pagination semantics (limit/start together) or which filters combine, which would be the remaining gaps 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?

Schema coverage is 75%, so most parameters are documented in the schema; the description still adds meaning by disclosing the default sort direction and the semantic effect of omitting folderId. It does not clarify interaction between sortBy/sortorder or the start/limit pagination contract, leaving some room.

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 (List) and resource (emails) with scope (a folder, or across folders when folderId is omitted) and default ordering. It does not explicitly distinguish itself from the sibling zoho_search_emails, so an agent must infer the enumeration-vs-search split rather than being told.

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 parenthetical 'across folders if folderId is omitted' gives an implied usage condition, but there is no explicit when-to-use/when-not guidance and no routing to the obvious alternative (zoho_search_emails) for query-driven retrieval. Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely new behavior the annotations do not: the response contains no unread count and the correct alternative for that need. It does not note pagination or result size limits, so it stops short of a 5.

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

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

Two sentences with no filler: the capability and return shape come first, and the corrective routing note follows immediately. Every clause earns its place.

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

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

No parameters and no output schema, so the description must supply the return shape itself — and it does, by listing the fields. Combined with the unread-count caveat and the sibling routing, nothing needed to call this correctly is missing.

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

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

The tool takes zero parameters, so there is nothing schema-level to explain and the baseline is 4. The description's enumeration of return fields compensates usefully for the absence of an output schema.

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

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

States a specific verb and resource ('List all folders') and even enumerates the returned fields (folderId, folderName, path, folderType, isArchived), so the agent knows exactly what comes back. It is clearly distinguishable from the sibling zoho_get_folder (single folder) by the 'all' scope.

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

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

Gives an explicit routing rule away from this tool: for unread mail use zoho_list_emails with status=unread instead, since this response carries no unread count. It lacks a positive 'use this when you need the folder tree' statement, so it is strong context rather than a full when/when-not pairing.

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=false, destructiveHint=false and openWorld=true. The description adds nothing beyond that: it does not say the email is moved out of the spam folder, whether the action is idempotent, what happens if the message was never spam, or what the response contains. For a state-mutating tool this is thin.

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

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

Two tight sentences, zero filler, with the action stated first and the targeting rule immediately after. Every clause earns its place.

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

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

No output schema exists, so the description should carry more of the behavioral burden for a mutation tool. It covers targeting adequately but leaves folder behavior, side effects and failure modes unaddressed.

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 50%, and the description compensates partially by stating that messageId and threadId are mutually exclusive alternatives. It says nothing about folderId or isFolderSpecific, so half the parameters rely entirely on the schema. The one-of constraint is the main added value.

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 ("Mark emails as not spam") and clarifies the two targeting modes, messageId vs threadId. It implicitly separates itself from zoho_mark_emails_spam and zoho_mark_threads_not_spam by describing both email- and conversation-level targeting, though it never names those siblings 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?

"Give one of the two" is a useful exclusivity constraint, but there is no guidance on when to prefer this over zoho_mark_threads_not_spam or zoho_mark_emails_spam, nor any prerequisite context (e.g. that the email must currently be in spam). Usage is only partially implied.

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 establish that this is a non-read-only (state-changing) but non-destructive operation, so the safety profile is covered. The description confirms the state change but adds no detail on reversibility, idempotency, permission requirements, or what happens to threads not in the given list. Adequate but thin 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?

Two front-loaded sentences with zero filler; the action comes first and the parameter rule immediately follows. Every clause carries information.

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

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

For a two-parameter mutation with no output schema and no required fields, the description is close but leaves gaps an agent needs: the array/multi-ID semantics, the error condition when neither ID is provided, and how it relates to the thread-specific sibling. Not inadequate, but not fully self-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?

With schema description coverage reported at 0%, the description must compensate, and it does partially: it explains what each ID refers to (message vs conversation) and their mutual exclusivity. But it omits that both parameters are arrays requiring at least one element, and it never states that supplying neither is invalid, leaving requiredness 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?

The description states a specific verb+resource ("Mark emails as read") and clarifies the two targeting modes. However, it does not distinguish itself from the near-identical sibling zoho_mark_threads_read, which appears to cover the same thread-level operation, so the boundary between them is left ambiguous.

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

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

It gives a clear conditional: use messageId for individual emails, threadId for whole conversations, and explicitly says to supply one of the two. What it lacks is any routing guidance relative to siblings like zoho_mark_threads_read or zoho_mark_emails_unread.

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 a non-read-only, non-destructive, open-world operation, so the safety profile is covered. The description adds genuine behavioral context beyond that by disclosing the concrete side effect (relocation to the Spam folder) rather than merely restating the name. It stops short of documenting reversibility, auth requirements, 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?

Two compact sentences, front-loaded with the operation and its effect, followed by the targeting rule. Every clause earns its place with no 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 mutation tool with no output schema, the definition covers purpose, side effect, and targeting adequately, and annotations carry the safety profile. It is slightly short on the folderId/isFolderSpecific relationship, but nothing critical to 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?

With 50% schema coverage, the schema does part of the work. The description adds a meaningful non-schema constraint by clarifying that messageId and threadId are mutually exclusive ('give one of the two'). It says nothing, however, about folderId or isFolderSpecific, whose interaction ('then folderId is required') is left entirely to 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?

It states a specific verb and resource ('Mark emails as spam') and immediately clarifies the concrete effect ('moves them to the Spam folder'). The scope note that it targets either individual messages (messageId) or whole conversations (threadId) helps separate it from thread-only siblings like zoho_mark_threads_spam and from zoho_mark_emails_not_spam.

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 clear context for invocation in two modes and adds a constraint ('give one of the two') that guides parameter choice. It does not, however, explicitly route the agent against alternatives such as zoho_mark_emails_not_spam, zoho_move_emails, or the thread-specific sibling, so exclusions are absent.

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 this is a mutation (readOnlyHint=false) that is not destructive (destructiveHint=false) in an open world. The description adds the targeting semantics (one ID type per call) but discloses nothing about permissions, batching, idempotency, or side effects of unread-marking. Against existing annotations, this is adequate but not 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?

Two sentences, zero waste, front-loaded with the action and followed by the parameter-routing rule. Every clause earns its place; nothing is redundant with the structured fields.

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

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

For a simple two-parameter mutation with annotations covering its safety profile and no output schema, the description is largely sufficient: the agent knows the action and how to target it. It omits confirmation behavior and any permission prerequisites, but nothing critical for correct invocation is missing.

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

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

Top-level schema description coverage is 0%, so the description must compensate and it does add real meaning: messageId addresses individual emails while threadId addresses whole conversations, and exactly one must be supplied. It does not explain the array/minItems shape or the string-precision note, so it is not fully complete.

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: 'Mark emails as unread.' It also clarifies scope by explaining that the target can be individual emails (messageId) or whole conversations (threadId). It does not explicitly distinguish itself from the close sibling zoho_mark_threads_unread, leaving potential ambiguity about which thread-marking tool to use.

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

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

Gives clear parameter-selection guidance: use messageId for individual emails, threadId for whole conversations, and 'give one of the two'. This tells the agent how to invoke it correctly. It stops short of naming an alternative tool or stating exclusions/conditions that would route away from this 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 supply the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description is not the sole carrier here. However, it adds no behavioral context of its own — nothing about what happens to the thread afterward, whether it returns to the inbox, or any permission/rate considerations. It essentially restates the name.

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

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

A single short sentence with zero filler and the core action front-loaded. It is efficient, though its brevity is part of the under-specification problem rather than a virtue here.

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 state-changing tool with 4 parameters and no output schema, the description leaves key questions unanswered: which folder the thread lands in after being un-spammed and how batch/multi-thread behavior works. Annotations cover safety but not outcome semantics.

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 75% and the schema already explains folderId's origin (zoho_list_folders), the 64-bit string caveat, and that isFolderSpecific requires folderId. The description contributes nothing about parameters, but the baseline of 3 applies since the schema does the heavy lifting.

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 ('Mark ... as not spam') with the scope qualifier 'whole threads', which implicitly distinguishes it from the email-level sibling zoho_mark_emails_not_spam. It does not name any sibling explicitly, so the differentiation must be inferred from the wording.

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

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

There is no guidance on when to use this versus zoho_mark_emails_not_spam or zoho_mark_threads_spam, no prerequisites, and no note on whether spam-marked threads must be restored to a particular folder. The agent gets no routing help from the description.

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

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

Annotations establish this is a mutating (readOnlyHint=false) but non-destructive operation; the description adds nothing beyond a restatement of the name. It doesn't explain the folder-scoping / archive interaction implied by isFolderSpecific and isArchive, nor that the action is irreversible for read-state purposes.

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

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

A single short, front-loaded sentence with zero padding, but its brevity stems from under-specification rather than efficiency given the tool has four parameters and mutation semantics to convey.

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 four-parameter mutation tool with no output schema and no indication of return values, side effects, or the archive/folder-mode interaction, one sentence is insufficient. An agent cannot tell from the description how batch thread marking behaves or what happens on partial failure.

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 75%, with the schema itself carrying useful detail such as the 64-bit string-precision warning and the folderId requirement when isFolderSpecific is true. The description contributes no additional parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb (mark), resource (whole threads), and resulting state (as read). The word 'threads' vs. 'emails' implicitly distinguishes it from sibling zoho_mark_emails_read, though it never names the sibling 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 when-to-use guidance, no prerequisites, and no mention of when to prefer this over zoho_mark_emails_read or zoho_mark_threads_unread. The agent must infer the thread-vs-email choice purely from the tool name.

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

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

Annotations already declare readOnly=false, destructive=false and openWorld=true. The description adds nothing beyond the name — it doesn't say what 'marking as spam' does (move/reclassify), whether it is reversible, or what happens to already-archived threads. With annotations covering the safety profile, the remaining behavioral burden is unmet.

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

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

A single short sentence, front-loaded and waste-free. It is efficient, though its brevity shades into under-specification rather than ideal conciseness.

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 exists and this is a 4-parameter mutation tool whose behavioral consequences are entirely undisclosed. The description leaves the agent without enough context on effects or the isArchive/isFolderSpecific interactions.

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 75% and the schema documents threadId, folderId and the isArchive/isFolderSpecific flags in detail. The description contributes no parameter meaning at all, so this is the baseline 3 where the schema does the heavy lifting.

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 ('mark whole threads as spam') and the scope word 'whole threads' distinguishes it from the email-scoped sibling zoho_mark_emails_spam. It doesn't explicitly name an alternative, 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, no mention of the counterpart zoho_mark_threads_not_spam, and no prerequisites. Usage is only implied by the name.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, lowering the bar, but the description adds nothing beyond the title: it does not say whether read flags are cleared, whether the operation is idempotent, or how folder-scoped vs. archive targeting behaves.

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

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

A single front-loaded fragment with zero waste. It is appropriately sized for its content, though the extreme brevity reflects under-specification rather than disciplined conciseness.

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 4-parameter mutation with no output schema, the description omits the meaningful behaviors an agent needs: how threadId arrays are processed, what isArchive and isFolderSpecific do in combination, and when to prefer this over the read/email-level variants.

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 75%, with folderId, threadId, and isArchive/isFolderSpecific documented inline (including the 64-bit string-ID caution and the folderId dependency). The description contributes no parameter meaning at all, so the baseline 3 applies rather than higher.

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 ('mark ... as unread') and the scope qualifier 'whole threads', which distinguishes it from the email-level sibling zoho_mark_emails_unread. It does not, however, explicitly name or contrast with the nearest alternatives (zoho_mark_emails_unread, zoho_mark_threads_read).

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

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

There is no guidance on when to use this tool versus zoho_mark_emails_unread for single messages, or versus zoho_mark_threads_read. No prerequisites, batch limits, or exclusions are mentioned.

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 declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the mutation/open-world profile is already covered. The description adds the mutual-exclusion constraint, but says nothing about what happens to the source folder, whether the move is reversible, or permission/rate-limit requirements for a write operation.

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

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

Two tight sentences, front-loaded with the action and then the targeting rule. 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?

No output schema, so the description carries return-value burden too. It covers the key targeting choice but omits the semantics of isArchive, isFolderSpecific/folderId, and the required destfolderId, leaving real gaps for a 6-parameter mutation tool.

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 67%, so much parameter meaning comes from the schema. The description adds genuine value by stating messageId and threadId are mutually exclusive (the schema does not enforce oneOf), but it never explains folderId, destfolderId beyond its name, isArchive, or isFolderSpecific.

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 emails to another folder') and clarifies scope (individual messages vs whole threads). However, it doesn't distinguish itself from the sibling zoho_move_threads, which overlaps with the threadId path described here, leaving an agent to guess which tool to pick for conversations.

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 parameter-selection guidance ('give one of the two'), which is useful, but offers no when-to-use guidance relative to siblings like zoho_move_threads, zoho_archive_emails, or zoho_delete_email. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds nothing beyond that — it does not say whether the thread is removed from the source folder, whether archive state is preserved, or what happens on partial failure across multiple threadIds.

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 sentence with zero filler. It is efficient, though arguably too terse for a 5-parameter mutation tool, since a second sentence on threading/archival behavior would have earned its place.

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

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

For a 5-parameter, multi-ID mutation with no output schema and no annotations explaining semantics, the description omits the isArchive and isFolderSpecific/folderId interaction entirely. An agent must infer required combinations from the schema alone, which leaves notable 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 80%, so the schema itself documents folderId, threadId, destfolderId, isArchive, and isFolderSpecific with useful notes about string-encoded 64-bit IDs. The description adds no parameter meaning at all, so the baseline 3 applies.

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

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

States a specific verb ('Move') and resource ('whole threads') with the destination ('another folder'), which is enough to separate it from zoho_move_emails (emails) and zoho_flag_threads. It does not explicitly name the sibling alternative, 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, no mention of prerequisites (e.g. destination folder must exist, IDs from zoho_list_folders), and no distinction from zoho_move_emails or zoho_archive_emails beyond the word 'threads'.

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 declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is already covered. The description adds real value by disclosing scope ("every label") and the either/or targeting constraint, but says nothing about auth requirements, reversibility, or whether labels are stripped across all folders.

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

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

Two tight sentences, front-loaded with the action and followed immediately by the targeting rule. No filler, no restatement of the title.

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

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

For a mutation tool with annotations covering the safety profile and no output schema, the description covers the core action and the key targeting decision adequately. It leaves the folderId/isFolderSpecific interaction (noted in the schema comment "then folderId is required") unexplained, which is a minor but real 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?

Schema coverage is only 50%, so the description must compensate. It clarifies the relationship between messageId and threadId ("give one of the two"), which the schema does not state, but it adds nothing for folderId or isFolderSpecific, leaving part of the parameter set under-explained.

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 ("Remove every label from emails") and explains the targeting split between messageId and threadId. This implicitly distinguishes it from the sibling zoho_remove_all_labels_from_threads, but the sibling is never named explicitly, keeping it just 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?

"give one of the two" communicates the mutual-exclusivity rule for messageId/threadId, which is genuine usage guidance. However, there is no when-to-use vs alternatives framing (e.g. versus the thread-scoped sibling or versus a partial label-removal tool), so the guidance 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 already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=false, so the safety profile is partly conveyed. The description adds the bulk-removal/whole-thread scope, which is useful behavioral context, but says nothing about reversibility, permissions, or rate limits. No contradiction with 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?

A single front-loaded sentence with zero filler. It is appropriately terse, though so brief that it omits details an agent at this complexity level would benefit from.

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 4-parameter mutation tool with no output schema, the description is thin. It covers neither the conditional use of isArchive/isFolderSpecific nor the distinction from the email-scoped sibling, leaving the agent to infer routing from the tool name 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?

Schema description coverage is 75%, so most parameters (folderId, threadId, isArchive, isFolderSpecific) are already documented with patterns and Zoho ID precision notes. The description adds no parameter meaning of its own, which is acceptable at this coverage level.

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 (remove), resource (labels), and scope (whole threads, every label), so the agent knows exactly what the operation does. It does not explicitly name the email-level sibling zoho_remove_all_labels_from_emails, though the resource scope implicitly separates them.

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 offers no when-to-use, when-not-to-use, or alternative guidance. It never explains when to prefer this over zoho_remove_all_labels_from_emails, nor when the isArchive/isFolderSpecific flags should drive selection.

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 declare readOnlyHint=false and destructiveHint=false but say nothing about timing or side-effect severity. The description usefully discloses that it 'sends real mail immediately' and mandates user confirmation, adding real behavioral context beyond the annotation profile. It stops short of covering scheduled-send (isSchedule) semantics, which the schema carries.

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

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

Two short sentences, zero filler, with the core purpose and the same-thread behavior front-loaded ahead of the send-warning. Every clause earns its place.

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

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

For a 15-parameter mutation with no output schema, the description covers what matters most: identity (reply in-thread) and side-effect risk. Parameter mechanics are well covered by the schema, so little is missing; only alternative-tool routing is absent.

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

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

Schema coverage is 80%, so the schema already documents the parameters (content, messageId, scheduleTime, attachments, etc.) thoroughly. The description adds no parameter-level meaning of its own, so the baseline 3 applies.

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

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

States a specific verb and resource ('Reply to an existing email') and adds the scope differentiator 'keeps it in the same thread', which cleanly separates it from the sibling zoho_send_email. An agent can identify the operation 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?

Provides a usage directive ('confirm with the user first'), which is genuine guidance, but never states when to prefer this over zoho_send_email, zoho_save_draft, or zoho_get_original_message. The 'when-not' and alternative routing are left implicit.

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=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description usefully adds the key behavioral fact that nothing is sent, plus the threading mechanism, but says nothing about account/auth requirements or what a successful save returns.

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

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

Two tight sentences, the non-sending constraint is front-loaded, and the follow-up sentence covers the one non-obvious parameter case. 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?

For a 13-parameter mutation tool with no output schema, the description covers purpose and one advanced parameter but omits mode semantics (draft vs template default), attachment usage, and the fromAddress ownership rule. Adequate minimum but with clear gaps against 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?

Schema coverage is 69%, so most parameters are self-documented, and inReplyTo/refHeader already carry examples in the schema. The description adds only derivational guidance ('from the original email's headers'), which is a marginal gain rather than compensating for the uncovered 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?

States a specific verb (save) and resource (email as draft/template) and explicitly contrasts with sending ('without sending it'), which distinguishes it from zoho_send_email and zoho_reply_to_email. It does not name those siblings directly, so 4 rather than 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?

Gives one concrete usage condition – how to produce a threaded reply draft via inReplyTo/refHeader – but never states when to choose this over zoho_send_email or zoho_reply_to_email, nor any prerequisites. Usage is implied rather than enumerated.

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 and openWorldHint, so the safety profile is covered. The description adds genuinely non-obvious operational behavior: the special "newMails" key, inclspamtrash, and groupResult, which an agent could not derive from the annotations or schema. It omits any statement about result ordering or pagination behavior, keeping it out of the top band.

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 and the joiner rule are front-loaded in the first sentence, and the dense parameter inventory is a legitimate syntax reference rather than filler. The example line is well placed at the end as a concrete anchor, though the run-on parameter enumeration is hard 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?

Given no output schema, the description should say more about what a result looks like, and pagination isn't addressed. It compensates well on the query-construction side, but result shape and the limit/start interplay remain unspecified for a tool whose whole job is returning a filtered set.

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 only 40%, so the description has to carry weight, and it does: it fully specifies the required searchKey grammar, the AND/OR joiners, every supported key, date format, and a worked example. The remaining parameters (limit, start, includeto) are left undescribed in both the schema and the description, which prevents a 5.

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 ("Search emails") and immediately names the query language (Zoho search syntax), which distinguishes it from sibling list/read tools like zoho_list_emails and zoho_get_email_content. It stops short of explicitly contrasting itself with zoho_list_emails, so an agent must infer the boundary between searching and listing.

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

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

Usage is only implied through the syntax reference and the example query; there is no explicit statement of when to prefer this over zoho_list_emails or how to fall back when the search syntax is unknown. The example ("subject:Invoice::sender:billing@acme.com::has:attachment") is helpful but is illustrative rather than prescriptive.

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 disclose readOnly=false, destructive=false, openWorld=true, but the description adds the crucial point that this 'sends real mail immediately' and should be confirmed with the user — an irreversibility/side-effect warning not captured by the hints. It doesn't describe failure modes or rate limits, but the human-in-the-loop warning is high-value 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?

Three sentences, zero filler: core purpose first, the safety warning second, the cross-tool prerequisite last. Each sentence earns its place and the most important (irreversible send) point is 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?

For a 14-parameter, no-output-schema tool, the description covers the highest-risk aspects (real send, user confirmation, attachment prerequisite) while scheduling and format details live in the schema. Nothing critical is missing, though failure/auth behavior is unaddressed.

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 79% (near the baseline-3 threshold), and the description adds meaning beyond the schema by tying the attachments parameter to the zoho_upload_attachment prerequisite and noting the returned objects must be passed through. It also implicitly links 'scheduled' to isSchedule/scheduleType, complementing the already-well-documented params.

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 an email') and covers optional modifiers (attachments, scheduled) that map to the schema. It's clearly distinguishable from closely related siblings like zoho_save_draft and zoho_reply_to_email, though it never names those alternatives 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?

Gives real operational guidance: confirm recipients/content with the user first, and call zoho_upload_attachment before this tool when attachments are needed. It stops short of naming sibling alternatives (e.g., save_draft vs send) or stating when-not-to-use, so it's clear context without 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 cover the safety profile (write operation, non-destructive, open-world), and the description adds valuable return structure `{ storeName, attachmentPath, attachmentName }` that would otherwise be unavailable since there is no output schema. It also explains the conditional inline URL behavior when isInline is true.

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

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

Two concise sentences that front-load the core purpose and immediately explain the return contract and usage in sibling tools. Every sentence earns its place with 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?

With no output schema, the description supplies the essential return shape and integration guidance with send/draft/reply tools. Together with annotations and full schema coverage, an agent has enough information 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 100%, so the baseline is 3. The description adds meaning for isInline beyond the schema's 'Upload as an inline image' by explaining it returns a URL usable as an <img src> in HTML content.

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 (upload) and resource (local file to Zoho for email attachment), and explicitly names the sibling tools that consume the result. An agent can easily distinguish it from download_attachment or get_attachment_info.

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?

Clearly states the use case—attaching a local file to an email—and directs the agent to pass the returned fields into `attachments` of zoho_send_email, zoho_save_draft, or zoho_reply_to_email. No explicit when-not guidance, 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.