Fluxmail

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

No annotations are supplied, so the description carries the full burden, and it does disclose a genuinely non-obvious behavioral trait: cancellation does not destroy content because the draft remains in Drafts. It does not cover idempotency, whether a confirm/force flag exists, or what happens if the schedule already executed.

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 zero filler; the action and its identifier are front-loaded, and the reassurance clause follows. Nothing redundant with the schema or 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?

An output schema exists, so return values need not be described, and the single parameter is explained. For a low-complexity mutation with no annotations, the description covers the main agent-facing risk (content loss) but leaves edge-case behavior (already-sent schedules, repeat calls) unstated.

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 a single parameter at 0% schema description coverage, the description must compensate, and it does: it explains that scheduleId identifies a pending scheduled send and traces its origin to send_email/sendAt or list_scheduled_emails. It adds no format or validation detail beyond that, but the origin explanation is the operationally important part.

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 ('cancel') and resource ('pending scheduled send'), scoped by scheduleId. It also names the sibling tools that produce the identifier (send_email with sendAt, list_scheduled_emails), so the agent can place it unambiguously against nearby tools like list_scheduled_emails.

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 identifies exactly where a valid scheduleId comes from, which effectively tells the agent when this tool is applicable. It stops short of stating exclusions (e.g. what to do if the send already fired), so it is clear context rather than 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?

No annotations are provided, so the description carries the full burden. It never states the key behavioral fact that creating a draft does not send the email, nor any account/permission requirements or what happens to derived recipients/subject. It discloses only the reply-derivation behavior, leaving important traits unstated 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, with the general purpose front-loaded and the reply-specific caveat second. No filler, though it is terse enough to leave gaps rather than being fully self-contained.

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. For an 11-parameter mutation tool with no annotations, however, the description is thin: it omits the draft-vs-send distinction and account requirements, leaving the agent to infer behavior from the schema 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 91%, so the schema already documents nearly all 11 parameters, establishing a baseline of 3. The description adds some value by explaining that recipients and subject are derived when replying, but doesn't extend meaning for the many other parameters (from, attachments, accountId, body variants).

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 clear verb+resource ('Create a draft') and additionally distinguishes the reply-draft mode from a plain draft via replyToMessageId. It doesn't explicitly name sibling tools like update_draft, but the reply-mode framing separates it from the other draft operations well enough.

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 guidance for the reply case (pass replyToMessageId, use replyAll for reply-all), which is genuinely useful conditional routing. However, it says nothing about when to use create_draft versus send_email or preview_send, nor any prerequisites for composing a new draft.

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 destructiveHint=true annotation already communicates that this is an irreversible mutation, so the description adds almost nothing behavioral. It does not state what gets removed, whether deletion is permanent or recoverable, or any permission requirements.

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 waste, which is appropriately sized. But brevity here reflects under-specification rather than efficient communication, so it earns only a middling score.

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

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

With an output schema present, return values need not be explained, but the description still omits usage context and leaves the required draftId undocumented while the destructive action is described only by the annotation. Incomplete for a 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 description coverage is only 50%: accountId is documented in the schema but draftId has no description at all. The description adds no parameter meaning, so it fails to compensate for the undocumented required identifier.

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

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

States a specific verb and resource (delete a draft), so the basic action is unambiguous. However, it does not differentiate scope from siblings like update_draft or create_draft beyond the verb, and reads largely as a restatement of the tool name.

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 no when-to-use guidance, prerequisites, or alternatives. There is no hint that update_draft should be used instead when modifying an existing draft, leaving the agent to infer selection 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it discloses that the tool returns metadata and a fetchable link rather than bytes, and that 'inline' embeds the bytes. It does not cover rate limits or link expiry, so it stays at a moderate level.

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 operation and immediately followed by the only non-obvious parameter instruction. No filler. Terse to the point of under-specifying scope, but structurally 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?

An output schema exists, so return values need not be described, and that is correctly left out. However, for a 4-parameter tool with only 25% schema coverage, the description should establish the account/message/attachment resolution chain and clarify that no bytes are downloaded unless inline is set. It hints at the latter but omits the former.

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 25%, so the description must compensate. It explains the undocumented 'inline' flag ('Set inline to embed the bytes'), which is the parameter most likely to confuse an agent, but accountId and messageId remain unexplained. Partial compensation lands at the baseline of 3.

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 pair ('Get attachment metadata and a fetchable resource link'), which is distinct from all siblings in the list. It is weakened slightly by the name 'download_attachment' implying byte retrieval while the description clarifies it actually returns metadata plus a link, a nuance the agent must reconcile.

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, nor any mention of the prerequisite chain (obtaining accountId/messageId/attachmentId from message metadata first). The only hint, 'returned by message metadata' in the schema, is not repeated or contextualized in 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 only supply destructiveHint=true, so the description carries the rest and does well: it discloses that the original body is quoted, the subject is prefixed with "Fwd:", attachments are included by default and can be suppressed, and where the comment lands. It does not mention auth/send-as requirements or idempotent-retry behavior, so it stops short of fully rich disclosure.

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

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

Two sentences, front-loaded with the action and resource, then packed with only decision-relevant behavior. No filler or restatement of the tool name.

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 the 8-parameter schema covers addressing and account selection. The description gives enough of the forward semantics to call it correctly; only auth/send-as context and retry semantics are 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 88%, so the schema already documents recipients, from, accountId, comment, and idempotencyKey. The description's notes on attachments and comment placement essentially restate the schema's own "Default true" and "Comment above the forwarded message" text, adding no new parameter-level meaning.

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 ("Forward") and resource ("an email") and immediately enumerates the resulting behavior: quoted body, "Fwd:" subject, attachments carried over. Forwarding is inherently distinguishable from send_email/create_draft, so an agent can select it without opening a 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?

Usage is implied by the semantics (use this when an existing message must go to new recipients rather than composing fresh), but there is no explicit when-to-use statement, no mention of preview_send or send_email as alternatives, and no prerequisites such as send-as permissions.

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 readOnlyHint annotation already declares this a safe read. The description adds genuine value by disclosing that outcomes can be 'uncertain', which tells the agent not to treat this as a binary success check. However, it says nothing about polling cadence, staleness, or how long results remain queryable.

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 that front-loads the outcome enum. Every word earns its place; 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?

An output schema exists, so return values need not be re-explained. But for a two-required-param lookup tool with zero schema descriptions, the description omits the critical provenance of operationId and any guidance on repeated polling, leaving the agent under-equipped to actually invoke 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% for two required parameters, and the description does not compensate: it never explains what operationId is or where it comes from (presumably the response of a send/forward call). The only hint of meaning is the word 'send or forward' implying the operation type. This is a real gap for a lookup tool that requires an opaque ID.

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 ('check') and resource (send/forward delivery operation) with the three possible outcome states, which is clearer than the bare tool name. It is distinguishable from the similarly-named sibling get_status, though it does not explicitly say how it differs.

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 call this versus get_status or the send/forward tools, and no mention that it is typically used after preview_send/send_email/forward_email to confirm delivery. The agent must infer the usage context 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?

The readOnlyHint annotation already establishes that this is a safe, non-destructive read, and the description merely restates 'Read' without adding context such as behavior on a missing draft ID, account resolution, or pagination. With annotations covering the safety profile and an output schema covering returns, the description contributes virtually nothing behavioral.

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 lookup key is stated up front and 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?

Annotations cover safety and an output schema covers return values, so the remaining burden is usage routing and the undocumented draftId. Those gaps leave it minimally adequate but not complete for an agent choosing among many get_*/list_* siblings.

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

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

Schema coverage is 50%: accountId is documented in-schema but draftId is not, and the description only partially compensates by stating the draft is identified 'by its draft ID'. It adds no format, sourcing, or constraint detail (e.g., length or where the ID comes from) beyond the schema.

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

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

The description states a specific verb (Read) and resource (draft), plus the lookup key (draft ID), so the operation is unambiguous. It does not distinguish itself from siblings like get_email or get_thread, which also read single entities by ID.

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 alternatives such as get_email, get_thread, or the list_* tools, and no mention of prerequisites like the draft needing to exist or be in a connected account. Usage must be inferred entirely 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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description usefully clarifies that attachments come back as metadata only (not downloaded), which is real behavioral context, but it says nothing about body truncation, size limits, or whether unread state is affected.

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 that lists the payload with zero 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?

An output schema exists, so return-value detail is not required here. What is missing is the usage routing versus get_email_body and documentation of the two undescribed parameters, leaving the definition minimally adequate for the task.

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 33% – accountId is documented in the schema while messageId and the bodyFormat enum are not. The phrase 'body (text and/or HTML)' loosely gestures at bodyFormat but never mentions the actual enum values (text/html/both/none) or that 'none' suppresses the body entirely.

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 ('Fetch one email in full') and enumerates what comes back (body, recipients, attachment metadata), which separates it from list_emails and search_emails. It does not, however, distinguish itself from the sibling get_email_body, so an agent choosing between the two gets no help.

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 despite a crowded sibling set that includes get_email_body, get_thread, and list_emails. The agent must infer from the name alone that this is the full-message fetch.

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?

readOnlyHint=true already establishes the safe-read profile, and the description adds the useful behavioral fact that the body is returned in bounded chunks requiring continuation. It does not disclose default/max chunk size behavior or what happens when offset exceeds the body length, so it adds moderate but not rich context.

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

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

Two short sentences, front-loaded with the core action and with the scoping word 'bounded' doing real work. The second sentence is terse and earns its place, though it introduces an incorrect identifier rather than pure waste.

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 5 parameters, 20% schema coverage, and no parameter documentation in the schema, the description leaves format selection, offset/maxChars interaction, and truncation behavior undefined. The existence of an output schema excuses it from explaining return values, but the input-side gaps are substantial.

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 20% (accountId is the sole documented property), so the description must carry offset, maxChars, and format semantics. Instead it references 'nextOffset', a name absent from the schema, which risks an agent fabricating a parameter; the real pagination parameter is 'offset'.

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

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

States a specific verb and resource with a distinguishing scope qualifier ('bounded portion of one email body'), which separates it from the sibling get_email/get_thread that likely return whole messages. It stops short of naming those siblings as the non-overlapping alternative, so the contrast must be inferred.

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 only guidance is 'Use nextOffset to continue,' which covers continuation but says nothing about when to choose this tool over get_email, nor any precondition on format or truncation. The guidance that does exist points at a parameter name that does not exist in the schema.

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, so the safety profile is covered. The description adds real behavioral context beyond that: the output varies by caller role (administrators see plan details) and it surfaces accounts needing re-authentication, which is why it doubles as a failure-triage 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?

Three short sentences, front-loaded with what the tool returns before the conditional admin behavior and the triage guidance. No filler or repetition of 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?

An output schema exists, so the description is not obligated to explain return values, and the role-conditional content note is the key caveat an agent needs. It could say more about what 'connection status' values mean, but for a zero-parameter read with a defined output schema it is sufficiently complete.

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

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

The tool takes zero parameters, so the baseline is 4. Nothing in the description contradicts or undermines the empty schema.

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

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

States a specific resource scope - account connection status and scheduled-send status - and adds the administrator-only visibility of plan details. It distinguishes itself from siblings like list_accounts and list_scheduled_emails by being a health/status overview rather than an enumeration, though the word 'status' alone remains somewhat broad.

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 explicit diagnostic guidance: 'Call this first if other tools fail,' which tells the agent exactly when this tool is the right entry point. It does not name an alternative or state when not to use it, so it stops short of a full routing rule.

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, so the safe-read profile is covered. The description adds useful context that content is paginated ('a page') and body content is 'bounded', but says nothing about how bounding works, defaults, or traversal 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, front-loaded sentence with no filler. It is efficient, though arguably too terse given the number of undocumented parameters.

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 returns need not be described, but four of five parameters (including the pageToken pagination contract and the bodyFormat enum) have no explanation anywhere. For a paginated read tool with this many options, the description is not sufficient to invoke it confidently.

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 20% (only accountId documented), leaving pageSize, pageToken, bodyFormat, and threadId without schema-level explanation. The description adds no parameter detail at all, so it fails to compensate for the coverage gap despite pagination and body-format being non-obvious.

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 (Fetch) and resource (a page of conversation messages), and the 'bounded body content' phrase signals it returns message bodies rather than metadata only. It is clearly distinguishable from get_email_body and get_email, though it does not 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?

There is no guidance on when to use this versus get_email, get_email_body, or search_emails. No prerequisites, no exclusions, no conditions for selecting this tool over its many siblings.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's main duty is additional context, which it only partly delivers. It does not mention whether unauthenticated or disconnected accounts appear, what 'status' values mean, or any scoping/rate constraints.

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 the verb and resource first and the returned fields in a compact 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 zero-parameter list tool with an output schema and a readOnly annotation, the description covers the essentials; the field list even previews the return shape. Minor gaps (status semantics, account scope) remain but are not blocking.

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 baseline is 4. The description correctly implies a no-argument enumeration and introduces no phantom 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 (List) and resource (connected email accounts), and the parenthetical names the fields returned. It is clearly a different resource from siblings like list_labels or list_send_as, though it does not explicitly differentiate itself from 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?

There is no guidance on when to call this versus alternatives such as list_send_as, which is the closest sibling and also enumerates account-level configuration. No prerequisites (e.g., authentication/connection state) 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?

The readOnlyHint annotation already establishes the safety profile, so the bar is lower. The description adds that results carry metadata with optional previews and that pagination is token-based, which is useful. It leaves unsaid what a page actually contains (no mention of result caps or snippet defaults), so it 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?

Four short sentences, front-loaded with purpose, then filtering, then pagination, then the alternative tool. The closing reassurance about browsers/other integrations is slightly promotional but does clarify that this is the canonical email access path.

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 shape need not be restated; the description still conveys metadata-vs-body behavior and pagination. Filtering breadth, pagination, and the body-fetch alternative are all covered. Minor gaps remain around the search-tool alternatives for a 16-parameter 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?

With 16 parameters at 63% schema coverage, the schema does most of the documenting (date formats, folder semantics, pageToken provenance). The description names filter categories — folder, sender, unread, dates — but adds no format or interaction detail beyond the schema. 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 — 'List emails from the user's connected mailbox' — and explicitly scopes the return to metadata plus optional previews. It routes full-content needs to get_email, so the agent can separate this from the body-fetching sibling. It does not distinguish itself from search_emails, the closest sibling, which is the only real gap.

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?

'Use get_email for full bodies' and 'Paginate with pageToken' give clear conditions for adjacent tools and continuation. It also enumerates the filter axes (folder, sender, unread, dates). It stops short of stating when to prefer search_emails or search_emails_batch over this tool, which is the natural alternative.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds the meaningful domain context that folders have roles such as inbox, sent, drafts, trash, spam, and starred, but it does not disclose additional behavioral details like pagination, account-scoping behavior, 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?

The description is a single front-loaded sentence with zero waste. It states the action, resource, scope, and returned role categories compactly.

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 output schema exists and the input schema has full description coverage, the description need not explain return values or parameter details. It adequately communicates the tool's purpose and folder-role semantics, though it could have distinguished this tool from list_labels more explicitly.

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

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

The single accountId parameter has 100% schema description coverage, so the schema already explains that it is optional when exactly one account is connected. The description adds no further parameter meaning beyond what the schema provides, making the baseline score of 3 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?

The description states a specific verb (List) and resource (navigable folders) and enumerates the folder roles returned. It does not explicitly distinguish itself from the sibling list_labels tool, but the folder-role enumeration makes the intended resource clear.

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 explicit when-to-use or when-not-to-use guidance and does not name alternatives such as list_labels. Usage is only implied by the listing of folder roles.

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?

readOnlyHint=true already establishes the safe-read profile, so the description's main added value is noting the result varies by provider (Gmail labels vs Outlook categories). It says nothing about pagination or ordering, and the output schema covers the return shape.

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 short sentence, front-loaded with the verb and the provider-dependent resource. Nothing extraneous.

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 the provider-dependence of the result is noted. The remaining gap is the ambiguity against list_folders, which a one-clause clarification would resolve.

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% for the single accountId parameter, so the schema already carries the semantics including the optional-when-one-account rule. The description adds no parameter detail beyond that baseline.

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 (Gmail user labels / Outlook categories), scoped to an account. It does not differentiate itself from the nearby list_folders sibling, leaving an agent to guess whether labels and folders are the same concept.

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 indication of when to use this over list_folders or other list_* siblings, and no prerequisites or exclusions stated. Usage must be inferred entirely 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?

readOnlyHint already covers the safety profile, so the bar is lower, and the description adds real value: sort order (pending first, then past), the status taxonomy (sent, failed, canceled), the meaning of lastError on failures, and the important operational caveat that pending sends only fire while the Fluxmail server is running.

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 tight sentences, front-loaded with the primary behavior and zero filler; each sentence (ordering, error field, server caveat) carries distinct 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?

Annotations cover the read-only safety profile and an output schema exists, so return-value explanation is not required; the description nonetheless sketches the return shape (sendAt, statuses, lastError) and the operational caveat, leaving nothing an agent needs 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?

Single parameter with 100% schema description coverage, so the schema already explains accountId and its optionality. The description adds nothing about the parameter, making the baseline 3 correct.

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 ('List scheduled sends') and immediately distinguishes itself from the list_emails/search_emails siblings by scoping to scheduled items and describing ordering and status categories. An agent can tell what it returns 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?

Usage is implied by the resource name, but there is no explicit when-to-use or when-not statement, nor any pointer to cancel_scheduled_email or preview_send as alternatives. Adequate but leaves routing 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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description's burden is reduced. It adds one useful scoping fact (results are tied to an account), but says nothing about ordering, emptiness, or whether the list is cached/dynamic.

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 short, front-loaded sentence with no filler or redundancy. Nothing to trim and nothing buried.

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-argument-required read tool with an output schema that covers the return shape, the description is close to sufficient. It still omits why an agent would need the list (e.g., picking a valid From address) and any note about result volume, leaving a modest gap for a multi-account mail workflow.

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 accountId parameter is fully documented in the schema, including the 'optional when exactly one account is connected' rule. The description's 'for an account' phrasing merely echoes that, 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?

The description uses a clear verb+resource pair ('List sender addresses') and scopes it to an account, so an agent immediately knows what it returns. It does not need to differentiate from siblings since no other tool in the list deals with send-as identities, but it also doesn't say so 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?

Usage is only implied: the agent can infer this is the tool to call before choosing a sender address for send_email, but the description never states when to use it or references a related tool such as send_email or preview_send. No exclusions or prerequisites are given.

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, and the description does not contradict that. However, beyond the annotation the description adds almost nothing about destructive behavior: it does not specify which actions are irreversible, whether delete is permanent versus trash, or what permissions are needed.

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 with the purpose front-loaded. The second sentence adds useful conditional parameter requirements without any 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?

For an 11-action destructive mutation tool, the description leaves major gaps: which actions are destructive, whether delete is permanent, and connection-dependent authorization details. The presence of an output schema means return values need not be explained, but behavioral context is still insufficient.

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

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

The description restates conditional requirements already present in the schema for folder and labels. It adds no meaning for the action enum or messageIds, and with only 60% schema description coverage it does not compensate for missing parameter details.

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 ('batch-modify emails') and notes the action set is connection-dependent. It is clearly distinct from read/list/send siblings, but does not explicitly differentiate itself from them by name.

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 only conditional parameter requirements ('Moving requires folder; labels require labels'), not guidance on when to choose this tool over alternatives or when not to use it. No alternative tools 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?

readOnlyHint=true already declares the no-mutation safety profile, and 'without sending' reinforces it rather than adding new information. The word 'resolved' hints that recipients/from are computed (e.g., from replyToMessageId or send-as addresses), which is useful, but nothing is said about validation failures, auth requirements, or what happens with invalid addresses.

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 that front-loads the verb and outcome, with zero filler. Everything it says 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 12-parameter, zero-required tool with an output schema and rich schema descriptions, the message is conveyed. It could go further by explaining how draftId and replyToMessageId interact with the preview, but the structured fields and output schema carry most of that burden.

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 83%, so the schema already documents nearly every parameter, including draftId, replyToMessageId, accountId, and the attachment object shape. The description adds no parameter-level detail beyond the field list, so the baseline 3 for high schema coverage 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 uses a specific verb ('Show') plus a concrete resource set (resolved sender, recipients, subject, attachments) and adds the crucial qualifier 'without sending', which cleanly separates it from send_email. It does not explicitly name send_email or forward_email as the sending siblings, so it falls just short of full 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?

Usage is only implied: 'without sending' suggests a dry-run preview before send_email, but the description never states when to prefer this over composing a draft (create_draft) or sending directly. No explicit when/when-not or named alternative is given.

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, so the safety profile is covered. The description usefully notes the account scope and the portable query capability, but says nothing about pagination behavior, result limits, or that rawProviderQuery only works on a single compatible account (schema-only detail).

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 core operation and followed by capability enumeration. No wasted text, though the second sentence is essentially a feature list.

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 required params are clear. But for a 16-parameter search tool with no usage guidance and gaps on pagination and provider-native queries, the description leaves meaningful holes 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?

With 16 parameters and only 63% schema description coverage, many fields (to, from, read, starred, subject, hasAttachment) have no schema description at all. The description lists the supported query operators, which partially compensates by implying which filters exist, but it does not explain rawProviderQuery, includeSnippet, includeSearchContext, accountId resolution, or pagination.

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 ('Search one account') and scopes it to a single account, which implicitly distinguishes it from the batch sibling. However, it never names search_emails_batch or list_emails, so the differentiation is left for the agent to infer.

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 the obvious alternative search_emails_batch for multi-account search. The 'one account' phrase hints at scope but does not route the agent explicitly.

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=true, so safety is covered. The description usefully adds that results are grouped per account with a shared query, but says nothing about pagination, page-token behavior across accounts, or rate limits for a 20-account fan-out.

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 tightly written sentence with no filler, front-loading the batch scope and grouping behavior. It is efficient, though arguably too terse for a 14-parameter tool.

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

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

Output schema exists so return values need not be described, but for a 14-param, 43%-covered tool with nested account/pagination semantics, the one-line description leaves the agent without enough guidance on filters, pagination, or multi-account error handling.

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 43% across 14 parameters, and the description adds meaning for just two concepts (the portable query and the 20-account cap). Filters like to/from/read/starred/folder and the per-account pageToken structure get no explanation anywhere, so the description fails to compensate for the coverage gap.

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

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

States a specific verb (search) and resource (emails) with a clear scope: batching up to 20 accounts in one portable query and returning grouped results. This implicitly distinguishes it from the single-account search_emails sibling, though it never names the alternative.

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 20-account cap and 'one portable query' framing imply this is the multi-account tool, but there is no explicit when-to-use vs search_emails guidance or any stated prerequisites. Usage must be inferred from the batch scope.

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

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

Annotations only declare destructiveHint=true; the description goes further by warning delivery is real, that scheduled sends are persisted as real drafts and depend on the server running (missed ones fire at next startup), and that sendAt returns a scheduleId. It doesn't cover auth/permission scope or idempotency semantics beyond what the schema says, 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?

Three dense sentences, front-loaded with purpose before modes and caveats, with no filler. Slightly packed with mode/caveat clauses, but every clause carries operational 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?

For a 14-parameter tool with an output schema and a single annotation, the description covers modes, scheduling caveats, and the confirmation rule. Gaps are minor: attachments and the required idempotencyKey are left entirely to the schema, and account selection (accountId) is only hinted at via 'the user's connected account'.

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 already 93% (baseline 3), and the description adds genuine cross-parameter structure the schema lacks: which parameter set defines each mode, that reply derives recipients/subject/threading from the original, and that sendAt composes with any mode rather than being its own mode.

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 ('Send an email from the user's connected account') and immediately distinguishes the three operating modes (direct, existing draft, reply), which lets an agent separate this from create_draft, update_draft, forward_email and preview_send.

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

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

Explicitly routes against alternatives: 'prefer it over browser automation or leaving a draft when the user asked to send', and adds a decision rule for ambiguity ('Confirm with the user when intent is ambiguous'). Mode selection conditions (direct vs draftId vs replyToMessageId) are spelled out.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the destructive semantic that this overwrites content wholesale rather than merging — an important trait beyond the schema — but says nothing about whether unspecified fields are cleared, error behavior, or account/auth requirements.

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 no waste and the key semantic front-loaded in parentheses. Appropriately sized, though it could have used one more sentence for usage context at little cost.

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 no explanation, and the schema covers most parameters. However, for a 12-parameter mutation tool with zero annotations, the description leaves gaps around failure modes, field-clearing behavior, and when to prefer alternatives.

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 83%, so the schema already documents nearly all 12 parameters with formats and examples. The description adds no parameter-level detail; the 'full replacement' note only indirectly hints that all content fields must be re-supplied.

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 (replace) and resource (draft), and crisply distinguishes itself from a partial-update tool. It implicitly separates from siblings like create_draft and delete_draft, though it doesn't name 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 'full replacement, not a patch' clause gives useful preconditions for how to invoke it, but there is no explicit guidance on when to choose this over create_draft or a modify tool, nor any mention of required preconditions such as the draft already existing.

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