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

Annotations are all false, so the description must carry behavioral context. It discloses that HTML is constrained (rejects remote resources, hidden content, message-box escapes), preserves empty paragraphs, and cannot send. These details add value beyond annotations and do not contradict them. It stops short of discussing result side-effects or failure modes, but is reasonably transparent.

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

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

The description is three sentences in length, opens with the core action, and delivers key constraints efficiently. Every sentence adds meaningful information without repetition or filler.

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

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

Given the tool's complexity (9 parameters, 0% schema coverage), the description is inadequate. It fails to explain most required and optional parameters, so an agent cannot confidently construct correct calls. The presence of an output schema doesn't compensate for missing parameter semantics. Only the HTML-related behavior is covered.

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

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

With 0% schema description coverage, the description must compensate for all 9 parameters. It only touches on the html_body parameter through 'authored HTML' constraints and vaguely references content preservation. It offers no guidance on account_id, to, subject, body, cc, bcc, attachment_names, or reply_to_message, leaving most parameters poorly specified.

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 'Save a draft' – a specific verb and resource. It also clarifies 'No send capability,' which disambiguates from any sending tool. However, it does not explicitly differentiate from the sibling 'update_draft,' so it falls 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 explicit guidance on when to use this tool versus alternatives like update_draft. The only hint is 'No send capability,' which implicitly rules out sending but doesn't name alternatives or conditions for selection. This leaves the agent to infer usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that only 'safe headers/plain text' is read, which is useful context, but it does not clarify truncation, what 'safe' means, or any auth/rate-limit behavior.

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

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

The description is extremely short for a tool with four required identity parameters and one optional content-limit parameter. It is not bloated, but it is under-specified to the point that brevity is a defect rather than 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?

An output schema exists, so return values need not be explained, and annotations cover safety hints. Still, the input identity is completely undocumented in both schema and description, and no usage context is supplied, leaving the definition inadequate for correct invocation.

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?

There are five input parameters, four of them required, with 0% schema description coverage. The description does not explain account_id, mailbox, uid_validity, uid, or max_text_chars, and the vague phrase 'one complete returned identity' does not provide usable semantics for the identity tuple.

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 verb ('Read') and a narrow content type ('safe headers/plain text'), so it is not a bare tautology. However, it never names the resource as an email and does not distinguish itself from siblings such as get_email_html or get_emails, and the phrase 'using one complete returned identity' is opaque.

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 when-not-to-use guidance, and no named alternative. The phrase 'using one complete returned identity' hints at a prerequisite identity from another call, but it does not identify which call or explain the selection context versus get_email_html, get_emails, or search_emails.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: 'strictly filtered HTML without remote loading' discloses that remote content is not loaded (privacy/security feature), and 'empty paragraphs are preserved' indicates a specific formatting behavior. This goes beyond what annotations provide.

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

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

The description is a single sentence that is concise and front-loaded with the core purpose ('Read strictly filtered HTML'). Every word adds value: 'strictly filtered' and 'without remote loading' convey important behavioral constraints, and 'empty paragraphs are preserved' adds a specific detail. 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?

The tool has an output schema (not shown in detail), which likely explains the return format, so the description doesn't need to cover that. The description covers the key behavioral aspects (filtering, no remote loading, empty paragraph preservation). Given the tool's moderate complexity (4 parameters, all required), the description is reasonably complete, though it could benefit from explaining the parameters or providing more context on when to use 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 description coverage is 0%, so the description must compensate for parameter meaning. However, the description doesn't explain any of the four parameters (account_id, mailbox, uid_validity, uid). The parameter names are somewhat self-explanatory (identifying an email), but the description adds no additional semantics beyond what the schema provides. With 0% coverage, the description should have provided more detail, but the parameters are standard email identifiers.

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

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

The description clearly states the tool reads filtered HTML from an email, specifying 'strictly filtered HTML without remote loading' and 'empty paragraphs are preserved'. It distinguishes itself from sibling tools like get_email and get_emails by focusing on HTML content with specific filtering behavior, though it doesn't explicitly name alternatives.

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

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

The description implies usage for retrieving HTML content with specific filtering requirements, but it doesn't explicitly state when to use this tool versus alternatives like get_email or get_emails. The context of 'strictly filtered' and 'without remote loading' suggests safety considerations, but no explicit when/when-not guidance is provided.

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

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

Annotations already declare readOnly=true, idempotent=true, non-destructive, closed-world, so the safety profile is covered. The description adds 'ordered partial results', which is genuinely beyond the annotations, but it is left vague – it never explains what causes partiality or what the ordering is keyed on.

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; the scope (plain text), the count bound (1-10), and the ordering/partiality note all earn their 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. However, with two parameters at 0% schema coverage, the description leaves the input contract (identity shape, text truncation) unexplained, which is a real gap for a batch read 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 description coverage is 0% and the description adds no parameter meaning at all. The required 'identities' array of nested objects (account_id, mailbox, uid_validity, uid) and the optional max_text_chars are both undocumented, and the description does not compensate – it never says how an identity is expressed or what max_text_chars truncates.

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 (Read) and resource (plain text of emails) scoped to '1-10 exact identities', which implicitly distinguishes it from get_email_html (HTML) and search_emails (search rather than exact lookup). It does not name a sibling explicitly, so it falls 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?

'exact identities' and '1-10' imply the context of use (batch fetch when you already hold precise message references), but there is no explicit when-to-use statement, no when-not-to-use, and no named alternative such as get_email for single messages or get_email_html for HTML bodies.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds a small amount of context with 'safe' and the prerequisite guidance, but does not elaborate on return characteristics, ordering, or any other behavior beyond what annotations provide.

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 core action, and every word earns its place. The prerequisite instruction is direct and adds meaningful guidance without redundancy.

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

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

For a zero-parameter listing tool with a full output schema and safety-related annotations, the description is complete. It tells the agent what to call and when to call it, leaving no critical gaps.

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

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

This tool has zero parameters, so the description does not need to explain parameter semantics. The baseline of 4 applies because there are no parameter-related gaps to compensate for.

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

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

The description clearly states the action ('List') and the resource ('safe account aliases'), making it distinct enough from sibling tools like list_mailboxes. It is concise and unambiguous, though it does not explicitly differentiate itself from all siblings.

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

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

The instruction 'Call this before using an unknown alias' provides an explicit when-to-use recommendation. It does not mention when not to use it or compare it to alternatives, but the usage context is concrete and actionable.

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 the tool as read-only, idempotent, and non-destructive. The description adds context beyond those by mentioning 'safe files' and the 'fixed attachment input directory', which clarifies the source and filtering behavior. It does not contradict annotations, though 'safe' is not further explained.

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

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

The description is a single, concise sentence (12 words) that is front-loaded with the action 'List' and delivers all necessary information without 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?

This is a simple list operation with no parameters and an output schema available, so the description need not cover return values. The description provides the essential context (read-only, fixed directory, safe files), but leaves a minor gap by not defining what qualifies as 'safe'.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly omits parameter details, and the empty schema requires no additional semantics.

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

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

The description uses a specific verb 'List' and identifies a unique resource: 'safe files available in readNdraft's fixed attachment input directory'. This clearly distinguishes it from sibling tools like list_accounts or save_attachment, which target different resources.

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

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

The description implies usage context through the phrase 'attachment input directory', suggesting it is used to enumerate files available for attachments. However, it gives no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives among the sibling tools.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful beyond-annotation context with 'isolated failures', disclosing that failures on one account do not prevent results for others. It also emphasizes 'exact' mailbox names, which hints at precision behavior.

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

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

A single concise sentence that front-loads the core operation ('List exact mailbox names') and packs in the key constraints: account count and isolated failure behavior. 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 simple one-parameter read-only tool with a rich annotation set and an output schema, the description covers the essential constraints: what is listed, for how many accounts, and what happens on partial failure. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 0%, but the single parameter account_ids is largely self-explanatory. The description adds value by specifying the '1-10 accounts' count constraint and per-account isolation, but it does not detail ID format, ordering, or error semantics beyond isolation.

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

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

The description states a specific verb and resource ('List exact mailbox names') and scopes it clearly to '1-10 accounts'. It is immediately distinguishable from sibling tools like list_accounts, which lists accounts rather than mailbox names.

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 when the tool is appropriate: when you need exact mailbox names for a bounded set of 1-10 accounts. It does not name explicit alternatives or exclusion cases, but the resource and scope make the intended use apparent.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the agent knows this is a destructive write. The description adds the constraints that the destination must already exist ('existing') and that the message/mailbox are 'ordinary' (not special types), providing some extra context. However, it does not disclose details about source deletion or failure behavior.

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

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

The description is a single, tightly worded sentence that front-loads the core purpose without filler. Every word contributes meaning.

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

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

Despite the annotations and output schema, the description is too sparse for a mutation tool with 5 required parameters and no parameter documentation. It lacks context on how to obtain the identifiers, the relationship between uid and uid_validity, and any prerequisites for moving an 'ordinary' message. The tool's overall behavior is underspecified.

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

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

Schema description coverage is 0%, and the description does not compensate. It mentions 'message' and 'destination_mailbox' but does not explain the meaning or format of uid, uid_validity, mailbox, or account_id. For a tool with 5 required params including the non-obvious uid_validity, this is a significant gap.

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

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

The description clearly states the specific action ('Move'), the resource ('one ordinary message'), and the destination ('an existing ordinary mailbox'). The word 'one' distinguishes it from the batch sibling move_emails_batch, making its sole purpose unambiguous.

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

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

The singular 'one' implies this tool is for single-message moves, suggesting batch moves should go elsewhere, but it does not explicitly name alternatives or state when not to use this tool. 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?

The description adds meaningful behavioral context beyond the annotations: it specifies the batch size limit (1-50), restricts messages to 'ordinary' types, and clarifies that all messages must originate from one account and go to one mailbox. This complements the destructiveHint annotation without contradicting it, though it does not mention potential partial failures or atomicity.

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

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

The description is a single, front-loaded sentence that conveys the core action and key constraints without any fluff. Every word carries meaning, making it highly concise and well-structured.

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

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

Given the tool's complexity (batch operation, 2 parameters, output schema present), the description covers the essential selection criteria: what it does, batch limits, and account/mailbox constraints. However, it leaves some ambiguity around 'ordinary messages' and does not address error handling or atomicity, which would be helpful but is not critical given the annotations and output 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?

With 0% schema description coverage, the description compensates by explaining that 'identities' represents the 1-50 messages to move (all from one account) and 'destination_mailbox' is the target mailbox. This adds crucial meaning that the schema property names alone do not convey, and it aligns with the required parameters.

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

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

The description clearly states the action ('Move'), the resource ('ordinary messages'), and the scope ('1-50', 'from one account to one mailbox'). It also implicitly distinguishes itself from the sibling tool 'move_email' by specifying batch size, making the purpose unambiguous.

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

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

The description implies usage for batch moves of 1-50 messages, but it does not explicitly state when to use this tool versus the single-message sibling 'move_email' or any other alternative. There is no mention of exclusions or conditions, so guidance is only 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?

The annotation declares readOnlyHint=true, but the description says 'Save one attachment,' implying a write operation to the filesystem. This is a direct contradiction, and the description does not clarify the tool's side effects, permissions, or overwriting behavior.

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

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

The description is a single concise sentence that conveys the core function and a key output detail. It is efficient and well-structured, though it omits critical behavioral context.

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

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

Given the tool requires 5 parameters, has no parameter descriptions, and includes a contradictory annotation, the description is far from complete. It does not address usage context, side effects, or parameter relationships, making it inadequate for reliable tool invocation.

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

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

The input schema has 5 required parameters with 0% description coverage. The description does not explain the role of any parameter, relying solely on parameter names. This is insufficient for an agent to understand how to correctly populate 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 clearly states the tool saves one attachment and specifies that saved_path is the absolute native-platform location. This clearly defines the tool's action and distinguishes it from sibling tools like list_attachment_inputs or get_email.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. It only describes the action without contextualizing its usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, covering the safety profile. The description adds a result-size range (1-500), stable ordering, and optional paging, which are useful behavioral details beyond annotations, though 'stable mailbox order' is ambiguous.

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

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

A single, front-loaded sentence with no wasted words. Efficient, though the phrasing 'metadata rows in stable mailbox order' is slightly jargon-heavy and could be clearer.

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 13 parameters, zero schema descriptions, and an output schema that covers returns, the description is far too sparse. It omits all search criteria and filter semantics, leaving an agent unable to select or invoke the tool effectively.

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

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

Schema description coverage is 0% and the description does not describe any of the 13 parameters. 'Optional paging' weakly hints at cursor/limit, but no meaning is added for filters like text, sender, subject, etc.

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 verb ('Search') and resource ('metadata rows') but does not explicitly say 'emails' and lacks any differentiation from siblings like get_emails or list_emails. The purpose is implied by context but vague and not clearly distinguished.

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 alternatives such as get_emails or list_mailboxes. No prerequisites, exclusions, or use-case scenarios 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 already declare idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description's 'idempotently' repeats the annotation, and the word 'one' adds minimal scoping context. It does not disclose additional behaviors like auth requirements or response semantics, but it does not contradict the annotations either.

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

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

The description is a single concise sentence with no filler and front-loaded purpose. However, it is almost too sparse, functioning as a fragment rather than a complete thought, which slightly reduces clarity despite its efficiency.

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

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

Given 5 required parameters, including IMAP-specific uidd_validity concepts, no schema descriptions, and the existence of a batch sibling, the description is insufficient. It does not explain how to identify the message or when to prefer the single vs batch variant, leaving the tool under-documented for reliable use.

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

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

Schema description coverage is 0% and the description explains none of the 5 parameters. Terms like uid_validity and mailbox are left undefined, so the description fails to compensate for the sparse schema and offers little meaning beyond parameter names.

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 'Set one read state idempotently.' uses a specific verb 'Set' and a clear resource 'read state', making the operation obvious. The word 'one' distinguishes it from the batch sibling set_read_state_batch, although it does not explicitly name the alternative, so it falls short of perfect sibling 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?

No guidance is given on when to use this tool versus set_read_state_batch or set_star. The singular 'one' implies a single-message use case, but there is no explicit context about prerequisites, exclusions, or alternatives, leaving the agent to infer usage.

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 idempotent and non-read-only nature. The description adds the constraint that a single read state is applied to all identities, and the batch size limit. It does not discuss failure modes or whether the operation is atomic, but the annotations reduce the burden.

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

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

The description is a single, focused sentence that conveys the core operation without any wasted words. Every word contributes to meaning.

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

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

The description minimally covers the operation but lacks details on batch semantics (e.g., whether partial failures occur) or when to choose this over the singular set_read_state. The output schema exists, so return values are covered, but overall the tool is underspecified for a batch mutation.

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

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

Schema description coverage is 0%, so the description must explain parameters. It loosely maps 'read state' to the 'read' parameter and 'identities' to the identity array, but does not clarify that 'read' is a boolean (true/false) or describe the structure of identity objects. Significant gaps remain.

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

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

The description clearly identifies the action ('Set'), the resource ('read state for identities'), and the batching scope ('1-50 identities'). It distinguishes from the singular sibling set_read_state by indicating the batch capability.

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 range '1-50 identities' gives clear context for when to use this batch version over the singular sibling. However, it does not explicitly mention alternatives or exclusion cases, so it misses the highest level of 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?

The description says "idempotently," which merely repeats the idempotentHint annotation. It adds no new behavioral context such as authentication requirements, error behavior, or the effect on other email metadata. Since annotations already declare idempotency and non-read-only status, the description adds minimal value beyond structured data.

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

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

The description is a single sentence with no wasted words. It is front-loaded with the operation (Set) and immediate qualifiers (one starred state, idempotently). Structurally, it is as concise as possible for the content it provides.

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

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

For a tool with five required parameters and no parameter documentation, the description is grossly incomplete. It lacks any mention of how to identify the target email, what the starred value means, or how to handle the response. While annotations cover idempotency and write behavior, they do not compensate for missing parameter context and usage instructions.

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

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

Schema description coverage is 0%, and the description provides zero explanation of the five parameters (account_id, mailbox, uid_validity, uid, starred). It does not indicate how these parameters relate to the email being starred, what the starred boolean controls, or how uid_validity is used. The tool is unusable without schema-level or description-level parameter semantics.

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

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

The description clearly states the tool sets one starred state, using the verb "Set" with a specific resource ("one starred state"). The qualifier "one" distinguishes it from the sibling set_star_batch, and "starred" separates it from set_read_state. While terse, it conveys the exact operation and primary 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?

No guidance is provided on when to use this tool versus alternatives like set_star_batch or set_read_state. The description does not mention batch operations, read-state operations, or any exclusions or prerequisites, leaving the agent to infer usage from the name alone.

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

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

Annotations already provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds only the 1-50 batch limit; it does not disclose behavior on partial failures, return format, or whether existing star states are overwritten. No contradiction with annotations.

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

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

The description is a single, succinct sentence with no redundant words. It is front-loaded with the action and scope, making it easy to parse.

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

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

For a tool with a nested object array and boolean parameter, the description is under-specified. It lacks context about uniform state application, error behavior, relationship to set_star, and what constitutes an identity. The output schema exists but does not substitute for usage clarity.

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

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

Schema description coverage is 0%, so the description must compensate. It hints at the 'starred' boolean ('one starred state') and mentions the identities array with a count bound, but it does not explain the structure of identity objects, the uniform application of the state, or the meaning of each parameter beyond what the schema types imply.

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

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

The description clearly states the verb ('Set'), the resource ('starred state'), and the scope ('identities', 1-50). It conveys batch behavior and distinguishes from the singular set_star tool via the count limit, though it does not explicitly mention the sibling tool.

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 guidance on when to use this batch tool versus alternatives like set_star or set_read_state_batch. It does not mention prerequisites, exclusions, or a recommended context.

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

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

Annotations already mark destructiveHint=true, and the description aligns by saying 'Replace a draft'. It adds valuable behavioral detail: HTML restrictions (permits normal layout CSS but rejects remote resources, hidden content, message-box escapes) and that empty paragraphs are preserved. It also clarifies it cannot send emails – useful context beyond annotations.

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

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

Three sentences, with the primary purpose front-loaded. It adds only relevant details about HTML constraints and capabilities, with no verbosity. Every sentence earns its place, making it highly efficient.

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 complex tool with 9 parameters and 0% schema coverage, the description is thin. It covers purpose and HTML constraints but omits parameter semantics, required field explanations, and side effects beyond replacement. The presence of an output schema doesn't offset the missing parameter guidance, so completeness is low.

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

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

Schema description coverage is 0%, so the description must compensate, but it provides no information about any of the 9 parameters. It mentions 'authored HTML' but does not tie it to the html_body parameter. Required parameters like account_id, draft_id, to, subject, body are unexplained, leaving the agent without guidance on how to construct a valid call.

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 'Replace a draft' – a specific verb and resource. It clarifies scope with HTML constraints and 'No send capability', which helps distinguish from send-related tools. However, it does not explicitly name siblings like create_draft, though 'replace' implies updating an existing draft.

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

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

No explicit when-to-use guidance is provided. The description implies use for updating existing drafts rather than creating new ones, but does not state conditions or alternatives. It also omits prerequisites like having a draft_id, so an agent must infer usage context.

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