Mail by Pony

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

Annotations already declare a non-destructive, idempotent, closed-world mutation, so the safety profile is covered. The description adds little beyond that: it does not mention the version-based concurrency expectation or what idempotency_key protects against, both of which matter for a write tool.

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

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

Two short sentences, front-loaded with the action, and the disambiguating negation earns its place. It is efficient, though efficiency here is partly achieved by omission.

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

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

For a four-parameter required mutation with no output schema and no parameter documentation, the description is too thin. An agent cannot learn from it how version conflicts are handled or what an idempotency key should contain, which are essential 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% and all four parameters are required, yet the description explains none of them. Only a faint implication links 'your draft' to draft_id; version, artwork_id (single enum), and idempotency_key remain unexplained in both schema and description.

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+scope: adds approved decorative artwork to a draft. The qualifier 'approved decorative' and the negation 'not purchased postage' narrow the intent well, though no sibling tool is named for contrast.

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 clause 'This is not purchased postage' implicitly excludes one use case, but there is no explicit when-to-use condition, no prerequisite state (draft must exist/be editable), and no alternative tool named.

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 annotations already declare destructiveHint=true and idempotentHint=false. The description adds useful context with 'Recoverably,' clarifying that the archive is reversible, but it does not explain recovery behavior, version requirements, or idempotency-key handling.

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 no wasted words. However, its brevity contributes to under-specification elsewhere rather than being fully appropriate for a three-parameter mutation 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?

For a destructive mutation with three required parameters, no output schema, and zero schema description coverage, the description is too sparse. It does not explain versioning, idempotency, or what recoverable archiving entails.

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 three required parameters. The description only indirectly hints at the draft being archived and provides no meaning for 'version' or 'idempotency_key,' leaving most parameter semantics undocumented.

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 names a specific verb and resource: archiving a draft. It also adds scope with 'current draft,' but it does not distinguish this from sibling draft operations such as update_draft or delete_template.

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, nor when not to use it. The phrase 'your current draft' implies context, but the agent must infer the selection conditions.

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 destructive=true, idempotent=true and openWorld=true, so the safety profile is covered. The description adds genuinely new behavior: a lifecycle cutoff (pre-preparation), a mandatory human approval gate, and the scoping fact that refunds are out of scope and tracked elsewhere.

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 dense sentence with the critical precondition stated first and no filler; the refund scoping clause earns its place. It is arguably too compressed for a destructive operation, but nothing is redundant.

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 destructive, open-world mutation with no output schema and zero schema coverage, the description covers the lifecycle gate and approval requirement but omits what happens on failure (order already in preparation), how idempotency_key should be used, and what the caller receives. Adequate, not complete.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it only obliquely gestures at "approved" and "grant_id" via "explicit user approval." The required order_id, the idempotency_key (min 8 chars, clearly intended for safe retries) and the const-true approved flag are never explained, leaving four undocumented 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 gives a specific verb (cancel) and resource (order, reinforced by the tool name) and scopes it with a precondition: only before preparation. It does not explicitly contrast with siblings like get_order, list_orders or reconcile_payment, so an agent must infer the boundary from the name alone.

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

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

"Cancel only before preparation" is an explicit when/when-not rule, and "after explicit user approval" states a prerequisite. It stops short of naming the alternative tool for post-preparation cases or for refunds, saying only that refunds are "separately tracked" — useful but not routable.

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 read-only, idempotent, non-destructive, closed-world behavior. The description adds a workflow sequence ('conversation/tools followed by the existing secure website studio'), but that phrase is cryptic and does not explain what the tool returns or any other behavioral traits.

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 entry-point cue front-loaded. The second sentence is somewhat vague but not wasteful.

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

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

With no output schema and no parameters, the description should clarify what information the agent receives back. It lists content categories ('option IDs, upload limits, payment readiness') but does not explain their format or how to use them, leaving the agent with moderate 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?

The tool has zero parameters, so there is no parameter semantics to explain. Baseline 4 is appropriate for a no-param tool.

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 the tool is for 'supported option IDs, upload limits and payment readiness', which gives some concrete content. However, the name 'catalog' is ambiguous and the description never uses a clear verb+resource pattern (e.g., 'returns a list of...'), leaving the exact purpose vague against a large set of specific sibling tools.

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

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

'Start here' explicitly signals when to use the tool as an entry point, and the mention of a default workflow adds context. It does not name alternatives or exclusions, but the primary usage cue is clear.

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

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

Beyond the annotations, the description adds useful behavior: the checkout is unpaid, consent is returned independently by the browser, retries should reuse preparation/consent, and redirects do not prove payment. These are meaningful operational caveats for a payment-adjacent tool. It does not contradict the annotations and adds context beyond idempotent/non-destructive hints.

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

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

The purpose and optional-workflow constraint are front-loaded, and the following sentences cover retries, the default alternative, and a payment-proof caveat without filler. The wording is dense and somewhat jargon-heavy, but each sentence carries relevant information.

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

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

For a consent-based checkout tool with no output schema and no parameter descriptions, the description covers the workflow, retry behavior, alternative path, and payment-proof caveat. However, it remains unclear what the tool returns, how the required IDs are validated, or what happens on failure. It is minimally adequate but has clear completeness gaps.

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

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

Schema description coverage is 0%, so the description must explain the two required IDs, but it only vaguely references 'preparation/consent' and 'browser consent.' It does not say what preparation_id identifies, where consent_id comes from, or how the two relate. This leaves the required parameters under-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 states a specific action: create an unpaid checkout under an optional consent workflow. It also distinguishes this path from the default website handoff, which helps separate it from sibling checkout/payment tools. The phrase 'independently returned exact browser consent' is opaque, but the core verb and resource are identifiable.

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

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

It explicitly scopes use to the optional consent workflow and notes that the default website handoff can finish payment without this agent step. It also gives retry guidance: reuse preparation/consent and reopen an existing order_url. The main gap is that it does not name prepare_checkout directly or spell out prerequisites for obtaining the two IDs.

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 say it is a non-readonly, idempotent, non-destructive, open-world call; the description adds substantive behavior beyond that: charges the prepaid balance, each item is drafted/proofed/final-quoted independently, results report queued or failed per item, retry-with-same-key resumes without double-sending, and 'queued' means not yet printed or mailed. That is exactly the kind of context annotations cannot convey.

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 the core action and scale, then item composition, retry semantics, and the queued caveat in descending priority. No filler or repetition.

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 batch mutation with no output schema, the description covers cost source, per-item outcomes, retry behavior, and the queued-state caveat. It stops short of saying how to check batch progress afterward (the get_batch sibling exists), which would close the last loop for an agent.

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

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

Schema coverage is low (33%), and the description compensates by explaining the two ways to populate an item (draft_id, or template_id + variables with recipient/sender) and the idempotency_key's retry semantics. It does not address content_policy_acknowledged, though the schema itself documents that field thoroughly, so the gap is minor.

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, and scale: 'Send up to 100 letters from the prepaid balance in one request.' The batch framing plus the prepaid-balance mention makes it immediately distinguishable from single-send siblings like send_with_credits, and the per-item composition is spelled out.

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

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

Gives clear operational guidance: items can be built from draft_id or template_id + variables, and retries must reuse the same idempotency key and body to resume without double-sending. It does not explicitly name alternatives (e.g., single-letter send or quote-before-send siblings), so the routing is implied rather than stated.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true). The description adds genuinely new behavioral context: the tool produces a hosted link and never moves money automatically, which is the key thing an agent must know before invoking a payment-adjacent 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?

A single tightly-packed sentence with the precondition front-loaded and zero filler. The phrase 'hosted funding link' is left unexpanded, slightly costing clarity for terseness.

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 write tool with no output schema and no parameter documentation, the description covers the safety-critical guardrails but not what the caller gets back (a URL? an id?) or how the idempotency key behaves. Adequate for a cautious agent, incomplete for an agent that needs the return value.

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 three required parameters. The schema does carry constraints (currency const USD, amount range 1–100000000, key length 8–150), but the meaning of amount_minor as minor units and the role of idempotency_key are left entirely to inference.

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 ('create a hosted funding link'), and clarifies the effect is a link rather than a charge. It does not differentiate itself from the lookalike sibling create_payment_link, which an agent could easily confuse it with.

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

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

Gives an explicit gating condition ('Only when the owner asks') and an explicit exclusion ('never automatically charge a card or top up after insufficient funds'). It stops short of naming alternatives such as create_payment_link or send_with_credits, so the agent must infer the routing itself.

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 non-readOnly, non-destructive, non-idempotent, so the safety profile is covered. The description adds genuinely new behavioral context (untrusted-content handling, prompt-injection resistance, preserving uploaded PDFs as files), but a large block is a verbatim repeat of the content_policy_acknowledged parameter description, and nothing is said about what state a draft lands in, that it is unsent, or about idempotency_key behavior despite the idempotentHint=false annotation.

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?

Purpose is front-loaded and the address guidance is tight, but roughly half the text is policy boilerplate duplicated verbatim from the schema's content_policy_acknowledged description, while the 14 undocumented non-address parameters get no space at all — the budget is misallocated rather than bloated.

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

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

For a 16-parameter, non-readOnly creation tool with no output schema and near-zero schema description coverage, the description should explain the draft lifecycle and the main content/formatting parameters. It covers only addresses and policy, so an agent still cannot confidently construct pages, content_type, decorations, or idempotency_key from this definition.

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 6% across 16 parameters. The description explains only the sender/recipient address path (inline fields vs *_id reuse) and PDF handling; text vs pages, content_type, style, paper, envelope, decorations, title, handwriting/original_hand configs, and idempotency_key are entirely undocumented in prose, leaving the agent to reverse-engineer them from names and enums.

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 opening sentence gives a clear verb and resource plus an important scope qualifier: 'Create a letter without ordering.' That separates it from checkout/send_with_credits, but it never names create_template_draft or update_draft, the siblings closest to it, so the boundary with those is left to inference.

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

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

It gives real operational guidance for addresses ('save customer-provided fields directly, or reuse confirmed address IDs', 'ask for missing details; never guess a ZIP'), which is useful when-to. But it never states when to use this over update_draft/create_template_draft, nor any prerequisite such as whether a draft must precede checkout, so usage is only partially routed.

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 cover idempotency and open-world/destructive flags, and the description adds real behavioral context beyond them: nothing prints or mails until payment confirms, an existing open order is reopened rather than duplicated, and a 422 address_incomplete error requires fixing the draft first. It also tells the agent to reuse the same key and arguments on retry, which reinforces the idempotentHint with actionable guidance.

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

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

The purpose and precondition are front-loaded in the first sentence, and each following sentence adds concrete value (payment gating, error handling, dedup, retry). Sentences are dense and long, but nothing is clearly wasted.

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

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

Despite no output schema, the description explains the return value (checkout_url plus a short summary), the approval mechanism, the failure mode (422 address_incomplete with remediation), and retry semantics. An agent has everything needed to call this correctly.

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

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

With 0% schema description coverage, the description compensates well: 'this exact saved draft version' clarifies draft_id/version, and 'reuse the same key and arguments on retry' explains idempotency_key's role. The mention of total_cents is slightly confusing since it is not an actual parameter, which keeps this from a 5.

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

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

States a specific verb and resource ('create (or reopen) its unpaid order and return a Stripe Checkout checkout_url') scoped to a saved draft version. The 'Pay-per-letter send' framing and draft/version scoping distinguish it from send_with_credits, checkout, and prepare_checkout without opening their schemas.

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

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

Gives a clear triggering condition: only after the customer explicitly approves sending this exact draft version, and notes that payment in Checkout is the approval so no sign-in or review is needed. It does not explicitly name sibling alternatives (e.g., send_with_credits) or state when not to use it, keeping it short of a 5.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful boundary that this does not create a draft or order, but it does not explain idempotency-key behavior or content-policy acknowledgement 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?

Two tightly written sentences, front-loaded with the core action and immediately followed by the key exclusion. No wasted wording.

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 an 11-parameter creation tool with very low schema description coverage and no output schema. The description explains the high-level purpose but leaves important required-parameter semantics and policy acknowledgement details under-specified for reliable 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 only 9%, so the description must carry most parameter meaning. It mentions text/Markdown, pages, style, paper, envelope, and sender, but omits required parameters like name, idempotency_key, and content_policy_acknowledged, as well as title and content_type.

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 ('Save') and resource ('reusable letter') and explicitly scopes it with 'Does not create a draft or order.' That exclusion directly differentiates it from draft-creating siblings like create_draft and create_template_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?

It gives a clear when-to-use signal ('Save a reusable letter... with {{variable}} placeholders') and an explicit when-not ('Does not create a draft or order'). It stops short of naming the alternative sibling tools, so it is not a full 5.

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

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

Annotations already declare non-readonly, idempotent, non-destructive. The description adds real value beyond that: it clarifies the output is an ordinary draft that is not auto-sent, and that incomplete variable substitution fails rather than producing a partial letter. It omits that a content_policy_acknowledged=true and an idempotency_key are mandatory, which are the two most likely failure modes.

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

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

Three short sentences with the 'Mail merge' category marker first and the key precondition second; nothing is redundant or 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 9-parameter nested-schema mutation tool with no output schema, the description leaves gaps: it does not say what comes back (a draft id/object) nor flag the two required fields that are not obvious payload data. Adequate to understand the concept, thin for calling it correctly on the first attempt.

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 22%, so the description needs to compensate. It covers the template source, variable substitution and the recipient/sender inputs, but says nothing about template_id, sender_id/recipient_id precedence over inline addresses, the idempotency_key, or the content policy flag.

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 ('create one ordinary draft from a template') and front-loads the 'Mail merge' framing, which distinguishes it from create_draft. It does not explicitly name create_draft as the non-template alternative, so sibling differentiation is implied rather than stated.

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

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

The phrase 'Missing variables are rejected' plus 'Proof, quote and send it like any draft' implies the downstream workflow and a precondition, but there is no explicit guidance on when to pick this over create_draft vs create_batch, and no stated prerequisites such as the content policy acknowledgment.

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

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

The description adds behavioral depth beyond the annotations, specifically clarifying the impact on dependent objects (draft/orders). This is a crucial detail for understanding the scope of the deletion's effect, making it more informative than the general 'destructiveHint'.

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 definition is highly concise, using only two short sentences. Every word is necessary, and the key behavioral constraint is front-loaded immediately after the action.

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

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

Given the low complexity (2 parameters) and the presence of strong annotations (destructive/idempotent), the description provides the necessary operational safety context. It is nearly complete, although it does not specify the expected success/error response format.

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

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

Schema coverage is 0%, meaning the description is expected to compensate. However, it fails to provide any semantic meaning or context for the two required parameters, 'template_id' and 'idempotency_key,' making it functionally reliant on the schema definitions.

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 ('Delete a template') and the target resource ('template'). While it does not explicitly compare itself against siblings like 'create_template' or 'get_template', the specific verb and context provide sufficient clarity.

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 a critical usage guideline by stating that 'Drafts and orders created from it are unchanged.' This is vital context that helps the agent determine if the deletion is safe for a specific user workflow.

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. The description adds useful return-content context ('batch result and its per-item order IDs') but does not disclose error behavior when batch_id is unknown or any access constraints. With annotations covering the safety profile, this is adequate but not rich.

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

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

A single compact sentence that front-loads the action and resource with no wasted wording.

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

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

For a simple read-only tool with strong annotations, the description covers the core action and partial return content. However, it lacks guidance on batch_id provenance, failure behavior for unknown batches, and any output details, which leaves meaningful gaps for an agent.

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

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

Schema description coverage is 0% for the single parameter. The description only implies that batch_id identifies a stored batch; it does not explain where to obtain it, its format, or how it relates to create_batch. The schema supplies constraints like minLength/maxLength but no semantic 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?

The description states a specific verb and resource: 'Read a stored batch result and its per-item order IDs.' This clearly distinguishes a retrieval tool from the write-oriented sibling create_batch, though it does not 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?

There is no explicit when-to-use guidance, no conditions for choosing this over siblings like create_batch, and no prerequisites such as requiring a previously created batch_id.

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?

Read-only, idempotent, non-destructive, and closed-world behavior are already declared in annotations, so the description does not need to restate them. It adds useful workflow context about consent and order_url recovery, but leaves return shape, auth, and retrieval behavior unstated; with annotations covering safety, that is a moderate gap.

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

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

Two sentences, with the workflow condition front-loaded and no obvious filler. The wording is dense and slightly ambiguous, but it stays short and task-focused.

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

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

For a single-parameter read tool with no output schema, the description gives the workflow trigger and the states being checked, but omits the input's meaning and the returned data shape. It suggests the recovery use case but is not enough to call it confidently without inspecting schema or other tools.

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

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

The sole required parameter preparation_id has 0% schema description coverage and is not mentioned in the description, so the agent gets no explanation of what ID to supply or where to obtain it. The parameter name and min/max constraints are the only guidance.

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 explains that this belongs to an optional consent workflow and checks browser consent plus an existing order_url, but it never plainly states that it retrieves a checkout preparation by ID or what the result represents. The verb 'check' and the workflow context help separate it from duplicating checkout, but not clearly from siblings like get_order or prepare_checkout.

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

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

It gives a clear timing condition ('after return/uncertainty') and an explicit exclusion ('instead of duplicating checkout'), which helps an agent choose it in the recovery path. It does not name a sibling alternative or state prerequisites such as where preparation_id comes from.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds meaningful context by stating it contains no token, secret or permission to send — telling the agent this cannot be used to authenticate or authorize a send. It does not address return format, but that is a minor add.

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 its scope, with the security clarification in the second sentence. No filler text.

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, annotated read tool with no output schema, the definition covers what it returns (a client ID) and that it is not a credential. The only gap is that 'owner-created grant setup' is jargon left unexplained, leaving the agent to guess the downstream 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?

The tool takes zero parameters, so the schema carries the full parameter burden and there is nothing further the description could add. Baseline 4 applies for a no-parameter tool.

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?

A concrete verb ('Read') and a concrete resource ('your own client ID') make the operation unambiguous, and the reference to grant setup hints at the related list_agent_grants workflow. It stops short of a full sibling differentiation, but the core purpose is 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?

'for owner-created grant setup' implies the context in which to call it, but there is no explicit statement of when not to use it or which sibling tool (e.g., list_agent_grants) covers adjacent needs. Usage must be inferred from a single conditional phrase.

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 the specific constraint that 'Funding does not authorize sending,' which is vital behavioral context not covered by annotations. The annotations already confirm it is safe (readOnlyHint: true, destructiveHint: false). Without these annotations, the description would need to carry the full 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 definition is extremely concise and efficient. Both clauses are necessary: defining the read operation and stating the critical business logic constraint.

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 zero parameters and strong annotations confirming safety and idempotency, the description is complete. It covers the scope of the read operation and a critical business boundary. No additional information like output format is needed.

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?

Since there are 0 parameters (100% coverage), the baseline for parameter semantics is high. The description confirms that no specific parameters are required to read the balance.

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 ('Read settled USD service balance') and the resource being acted upon ('service balance'). While it doesn't use a strict sibling differentiation, the function of 'get_credit_balance' is obvious compared to siblings like 'create_credit_topup' or 'list_credit_transactions'.

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 provides a warning ('Funding does not authorize sending'), which acts as a constraint on usage. However, it doesn't specify *when* this is the right tool versus other balance inquiry methods, resulting in moderate guidance.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, open-world), and the description adds genuinely new context: the status returned is 'provider-confirmed' (i.e., authoritative/live, not cached), and a redirect must not be treated as payment evidence. That is real behavioral information an agent cannot get from the annotations, though it says nothing about latency, failure modes, or what the status values look like.

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 followed by the caveat; nothing is padded. It is arguably over-terse for the information an agent needs, but every sentence 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?

This is an open-world read with no output schema and an undocumented parameter, so the description carries most of the burden — yet it never says what the response contains (status values, amounts, provider references) or how topup_id maps to a record. The caveat is useful but far from sufficient 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% — topup_id has only type and length constraints, no meaning. The description never mentions the identifier at all, so it adds nothing about what a topup_id is, where to obtain one, or whether it accepts the provider's ID or an internal one.

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

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

It states the operation ('Read provider-confirmed funding status') but never names the resource being read — the top-up record identified by topup_id — leaving the agent to infer the object from the tool name. Siblings like create_credit_topup, get_credit_balance, and list_credit_transactions are not differentiated, so the boundary between this and the balance/transaction tools is unclear.

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 when-to-use, when-not-to-use, or alternative tool named. The line 'A redirect is never payment evidence' implicitly tells the agent to verify payment here rather than trusting a redirect, but it is a caution about interpretation, not routing guidance.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, and the description adds meaningful context: addresses are masked and uploaded PDFs/images, letter text, and saved fields must be treated as untrusted. It does not explain what 'reopen' changes, if anything, or return details, but it goes well beyond the annotations.

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

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

The first sentence is front-loaded and useful, and the security guidance is relevant to safe handling of untrusted draft content. The middle sentence is long but purposeful; overall the description is coherent and mostly 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?

The definition is adequate for a simple read-only tool with annotations covering safety, and it adds important content-handling cautions. However, with no output schema and no draft_id guidance, an agent still lacks information about what the draft response contains and how to obtain the identifier.

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 0% description coverage, and the description does not explain the meaning, source, or format of draft_id beyond implying a saved draft. For a single required identifier parameter, this leaves the agent without semantic guidance beyond the field name.

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

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

States a specific verb and resource: read or reopen the same saved draft, scoped to conversation or secure review. It does not explicitly differentiate itself from siblings such as list_drafts or get_template, but the purpose is clear enough to identify the operation.

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 implied usage contexts (conversation or secure review) but does not explicitly say when to use this tool instead of list_drafts, get_template, show_letter, or update_draft. It leaves alternative selection 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?

Annotations already establish that this is read-only, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds a meaningful side-effect boundary with 'Does not establish payment,' but it does not explain permissions, history scope, error behavior, or what 'history' includes.

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, front-loaded sentences with no filler. Both the purpose statement and the payment boundary 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?

For a simple one-parameter read tool, the description plus annotations are minimally sufficient to call it. However, with no output schema and no schema parameter description, the definition leaves order_id semantics and the scope of 'history' undocumented.

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 the single required order_id parameter. It only implies that the parameter identifies the order; it does not clarify order_id format, source, constraints, or expected value.

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

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

The description uses a clear verb+resource: 'Read your order status and history.' It distinguishes this as a singular order retrieval versus list_orders, but does not explicitly name or contrast with any 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?

It gives no guidance on when to use this instead of list_orders, cancel_order, or payment-related siblings. The phrase 'Does not establish payment' is a useful boundary, but it is not a usage routing rule or an alternative-selection guideline.

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, so safety is covered structurally. The description adds one genuinely useful behavioral caveat — that a 'ready' state does not imply human review — but it leaves what 'ready' refers to undefined and says nothing about what is returned.

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 compact sentence that front-loads the action, with no wasted text. Its brevity is efficient, though it shades into under-specification rather than pure economy.

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

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

With no output schema, no parameter documentation, and a one-line description, an agent lacks the essentials: what a proof represents, where to obtain a proof_id, and what the response contains. Only the readiness caveat is fully conveyed.

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 single parameter 'proof_id' has no documented meaning, format, or provenance anywhere. The description does not compensate, giving no hint about where a valid proof_id comes from or what its constraints mean.

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 verb 'Read' and the resource 'proof' are identifiable, and 'owned' signals an access boundary. However, 'immutable exact proof' is undefined domain jargon, and with no sibling tool covering proofs there is no anchor to disambiguate what a proof actually is.

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 any other tool, nor prerequisites such as how ownership or readiness is established. The trailing clause is a caveat about interpretation, not a when/when-not 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine context beyond them by disclosing what the call returns — placeholders and a masked default sender — which is valuable since no output schema exists.

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 telegraphic enough ('its placeholders and masked default sender') that the grammatical attachment to 'template' takes a moment to parse, keeping it just below top marks.

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 one-parameter read tool with full annotations and no output schema, the description covers the essentials of what comes back. It omits error behavior when a template id does not exist and any guidance on sourcing the id, leaving it merely adequate.

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

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

Schema description coverage is 0% for the single required parameter, so the schema says nothing about template_id beyond type and length. The description never explains that the parameter is the template identifier or where to obtain it, so it 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?

The description uses the specific verb 'Read' with the resource 'one template' and lists the returned components (placeholders, masked default sender). 'One' implicitly separates it from list_templates, but no sibling is named 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: fetch a single template by id, presumably after list_templates has produced the id. There is no statement of when to prefer create_template_draft, update_draft, or delete_template, and no preconditions 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 establish read-only, idempotent, non-destructive, closed-world behavior. The description adds meaningful context beyond annotations by stating that only address IDs are returned and precise addresses are never exposed, which is important privacy and return-shape information.

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 compact sentence with no wasted words. The key resource and privacy constraint are front-loaded and immediately useful.

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 read-only listing tool with rich annotations, the description is largely complete: it explains what is listed and clarifies that precise addresses are not returned. It does not describe pagination, ordering, or exact response format, but those omissions are minor given the tool's simplicity.

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 there are no parameter semantics to document. The baseline for zero-parameter tools is 4, and the description does not need to compensate for missing parameter information.

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 address IDs. It also scopes the resource to addresses confirmed in the first-party website and clarifies that precise addresses are not returned, 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 when the tool is useful by specifying first-party website address IDs, but it does not explicitly say when to use it versus alternatives or when not to use it. No sibling tool appears directly comparable, so the implied usage is adequate but not fully guided.

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, closed-world and non-destructive, so the description adds real value by scoping the result (owner-created grants and remaining caps) and by disclosing an authorization boundary agents cannot cross. It does not describe return shape or ordering, but the broader safety profile is covered.

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 no filler; the operation comes first and the constraint second. Every clause carries information an agent could act on.

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 read tool with full annotation coverage, the description gives enough to select and invoke it: what is returned at a high level and what cannot be done. Without an output schema, more detail on the shape of 'grant' and 'caps' records would help, but the essential calling information is present.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a parameterless schema applies. The description correctly implies the scope is fixed to the calling client rather than selectable.

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 (owner-created standing grants plus remaining caps), which is clearly distinct from all listed siblings, none of which touch grants. Slightly less crisp because 'this client's' implies context the agent must already hold, and the second sentence restates a permission boundary rather than the operation.

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?

'Read this client's ... grants' indicates a read-only listing use case, and the exclusion 'Agents cannot create or widen grants' rules out a mutation path. However, no alternative tool is named and no condition is given for when an agent should call this versus other inspection endpoints.

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, so the safety profile is covered. The description adds genuinely useful behavior beyond that — records are append-only (immutable) and results are ordered newest first — but says nothing about pagination mechanics, the default page size, or whether a cursor expires.

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, front-loaded with the resource and carrying two useful qualifiers with zero filler. Nothing is wasted.

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

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

For a simple two-parameter list tool with no output schema, the description establishes purpose and ordering but omits paging guidance and any hint of what a transaction record contains. Adequate to call it, not quite enough to call it correctly on a multi-page history.

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 both parameters (limit, cursor) arrive undocumented and the description never mentions either. The names are conventional, but there is no statement of the default limit, the 1–100 range, or how to obtain and reuse a cursor, leaving the description to compensate for the gap and not doing so.

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

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

States a specific verb and resource ('Read your ... credit history') plus two scoping facts: the history is append-only and returned newest first. It is clearly distinguishable from the balance-oriented sibling get_credit_balance, though it never names that sibling explicitly.

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

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

Usage is only implied: 'history' versus a point-in-time balance suggests when to pick this over get_credit_balance, but the description gives no explicit when-to-use or when-not rule and does not mention the topup/transaction 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?

The annotations already establish that this is a safe, read-only, idempotent, non-destructive, closed-world operation. The description adds that results are scoped to 'your saved drafts,' but it does not disclose ordering, pagination, or whether archived drafts are included.

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 short sentence with the verb and resource front-loaded. It contains no filler or redundant restatement.

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 low complexity and rich annotations, the description is minimally adequate for invoking a no-parameter list tool. However, it leaves meaningful ambiguity about whether archived drafts are included and what the response shape is, which matters because there is no 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?

The tool has zero parameters, so there is no parameter semantics burden beyond what the empty schema already communicates. The description is appropriately silent on inputs.

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 gives a specific verb and resource: 'List' and 'saved drafts.' It is clearly a collection-listing tool, but it does not explicitly differentiate itself from siblings such as get_draft, list_templates, or archive_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?

There is no explicit guidance on when to use this tool versus alternatives. An agent can infer that it lists drafts, but it is not told when to choose get_draft, list_templates, or whether archived drafts are included.

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, non-destructive, and closed-world, so safety is covered. The description adds only that statuses are included in the response. It says nothing about pagination, result limits, ordering, or which orders are returned.

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 single sentence is front-loaded and contains no padding, but its brevity reflects under-specification rather than efficiency for a filtering list operation.

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?

There is no output schema and no annotation that documents results. The description therefore needs to explain the return shape, pagination, and the role of client_reference, and it does none of these.

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 parameter client_reference has 0% schema description coverage, and the description never mentions it. An agent cannot tell whether it filters the list, whether it is a prefix match, or whether omitting it returns all orders.

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 and resource ('List your ... orders') and says the results include statuses. The qualifier 'actual' hints that this is distinct from draft-oriented siblings such as list_drafts, but it never names or contrasts them 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 choose this over sibling tools like get_order or list_drafts. The agent must infer that list_orders lists orders and get_order retrieves one order.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds useful context that returned templates include variable names, but it does not mention ordering, pagination, or whether all saved templates are returned.

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 no wasted words. It directly states the resource and key return detail.

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 read-only list tool with annotations covering its safety profile, the description is largely complete enough to invoke. Because there is no output schema, the return shape is only described at a high level, leaving ordering and pagination unspecified.

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 empty schema requires no parameter explanation from the description.

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 resource ("saved letter templates") and adds that variable names are included. It does not explicitly distinguish this from siblings like get_template or create_template, but the list-vs-get distinction is still understandable.

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 explicit when-to-use guidance, exclusions, or comparison to alternatives such as get_template for a specific template. An agent must infer usage from the verb "List" 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 establish this is a non-destructive write that is not open-world. The description adds genuinely new behavioral detail beyond the annotations: two distinct output routes (handoff_url going to the website studio vs. review_url being the separate agent-consent route), and the retry/idempotency-key guidance. It does not fully describe the response shape, but the route distinction is useful behavioral context.

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

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

Three dense sentences with the core purpose front-loaded and the routing/idempotency notes following. It is efficient for the amount of routing nuance it conveys, though the opening clause is slightly abstract before the concrete "saved letter and quote without payment" clarification lands.

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

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

For a mutation tool with no output schema, the description usefully explains the two returned URLs and retry behavior. However, it leaves the meaning of draft_id and version unexplained and does not state what exactly gets created or persisted, which is a meaningful gap for a non-readOnly operation. Adequate but with clear omissions.

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

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

Schema description coverage is 0%, so the description must compensate for all three required parameters, but it only addresses idempotency_key ("reuse the same key on retries"). draft_id and version are left with only their type/constraint metadata and no semantic explanation. This is a clear gap for a tool the agent must call with three required args.

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 names a specific action ("prepare") on a specific resource (a saved letter and quote) and explicitly distinguishes it from the paid path by saying "without payment." The phrase "independent consent workflow" is somewhat jargon-heavy but the core operation is clear. It maps well against the sibling 'checkout' by contrasting payment vs. no payment.

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?

"Optional independent consent workflow" implies this is a non-default path, but it never states the condition under which an agent should choose it over 'checkout', 'quote', or 'quote_for_send'. The comparison to default checkout is implicit rather than spelled out. The agent must infer when to use this versus the primary paid flow.

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

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

Annotations already establish that this is a non-read-only, idempotent, non-destructive operation. The description adds meaningful behavioral context beyond annotations: tool success does not guarantee inline display, and address/envelope details plus final approval/payment remain browser-side. It does not contradict the annotations.

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

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

The description is short and front-loads the purpose before adding caveats. Each sentence serves a purpose, though the phrasing ('existing website', 'stay in that browser') is slightly terse 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?

For a write operation with no output schema and 0% parameter description coverage, the description is incomplete. It omits parameter semantics, especially idempotency_key, and does not explain what the returned proof or review_url looks like beyond naming the URL.

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters, but it mentions none of them. draft_id and version are inferable from names, but idempotency_key is entirely unexplained, leaving an important 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 states a specific verb and resource: generate the current exact print proof and a secure review_url. It is clear enough to distinguish from a generic proof-getter, but it does not explicitly name or contrast with sibling tools like get_proof or show_letter.

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 caveats: this is for proofing an existing website before final approval/payment, which stays in the browser. However, there is no explicit when-to-use guidance and no direct comparison to alternatives such as get_proof or show_letter.

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?

It adds real context beyond annotations: the result is bound to a specific revision, and 'Missing prices are unavailable, never zero' discloses failure semantics rather than silent zeroing. But annotations declare readOnlyHint=false and idempotentHint=false for what reads like a lookup, and the description never explains why the call is not read-only, whether it records anything, or why repeated calls could differ.

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 is returned, followed by scoping and error semantics. Each sentence contributes; the only weakness is that 'secure checkout' is a paraphrase rather than a concrete sibling reference.

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 does say what the quote includes (print/postage/options) and what it excludes (tax, final total), which is useful given there is no output schema. It still leaves the return shape underspecified (currency, per-item breakdown) and says nothing about the required draft_id, which leaves gaps for a two-required-parameter call.

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

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

Schema coverage is 0%, so the description must carry the load. 'Revision-bound' hints that the version parameter selects which revision is priced, but neither parameter is explained: draft_id is never mentioned, and there is no guidance on what version numbering means or how stale versions behave.

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

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

States a specific verb and resource: 'Get a current revision-bound subtotal' of print/postage/options. It implicitly separates itself from the payment path by noting that tax and the final total come from secure checkout. It does not name sibling tools directly, so an agent must infer the boundary with checkout/prepare_checkout/quote_for_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?

'Tax and full final total are shown by secure checkout before payment' implies this tool is for previewing the subtotal rather than completing payment. However, this routing is only implied, and the description never explicitly says when to call this tool rather than quote_for_send or prepare_checkout, nor does it state prerequisites.

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 cover safety and idempotency hints: readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true. The description adds meaningful context that tax is collected under current merchant policy, that the existing quote is subtotal only and cannot authorize credit spend, and that the same key/body should be reused after uncertainty. It does not describe permissions or response details beyond the quote itself.

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 tight sentences with the main purpose front-loaded. The contrast with the existing quote and the retry instruction both add useful information without filler.

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

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

For a tool with five required parameters, no schema descriptions, and no output schema, the description leaves most call requirements undocumented. It clarifies the quote's purpose and retry behavior, but an agent would still lack guidance on draft_id, version, proof_id, and send_intent_id.

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 six parameters, so the description must carry parameter meaning. It only hints at client_reference and idempotency_key/body, while leaving draft_id, version, proof_id, and send_intent_id unexplained.

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: obtain an exact final prepaid quote with tax collected under current merchant policy. It also distinguishes this from the existing quote, which is subtotal only and cannot authorize credit spend.

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 explains when to use this tool by contrasting it with the existing quote, which cannot authorize credit spend. It also gives retry guidance: reuse the same key/body after uncertainty. It does not explicitly name a sibling alternative or list exclusions.

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

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

The annotations already establish that this is a write operation ('readOnlyHint: false') and that it is idempotent. The description adds functional context—the act of matching a saved order against the provider—which is helpful, but it doesn't add technical behavioral traits like rate limits or specific error modes beyond the hint.

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 definition is perfectly sized for its task. It is front-loaded, concise, and avoids any superfluous phrasing, making it immediately clear to the agent.

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 extremely minimal input schema (1 parameter, 0% coverage), the description provides a necessary functional context. It defines the goal of the tool well enough for an agent to decide if it's the correct tool to satisfy a user request about payment matching.

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?

Since schema description coverage is 0%, the description's job is crucial. It adds meaning by clarifying that 'order_id' refers to a 'saved order,' but it does not elaborate on the required format of the ID beyond what is stated in the schema.

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

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

The description clearly defines the action ('Reconcile') and the specific objects involved ('saved order' and 'actual payment provider'). It distinguishes itself from read-only tools like 'get_order' or 'get_proof' by implying a data matching or state-changing operation.

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 tool lacks guidance on when to call it. It does not specify the required preceding steps, such as calling 'checkout' or 'create_payment_link', nor does it distinguish its role within the overall payment lifecycle.

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, so the bar is lower, but the description still adds real value by disclosing the blast radius: removing the attachment also removes its artwork placements, while existing orders are left untouched. It does not explain why a required idempotency_key is present despite idempotentHint=false, which would have been useful for a destructive call.

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 first and zero filler; the destructive scope and its boundary are stated in one compact clause pair.

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 destructive mutation with four fully undocumented required parameters and no output schema, the description covers the 'what gets destroyed' question but leaves the parameters, version preconditions, and idempotency behavior unexplained. Adequate orientation, insufficient 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% for all four required parameters, so the description needed to compensate and does not. It never explains what draft_id, file_id, version, or idempotency_key mean, nor the concurrency/retry semantics implied by 'version' and 'idempotency_key'.

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

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

States a specific verb and resource ('Remove a draft attachment') plus the cascading scope ('and its artwork placements'), and bounds it by noting existing orders are unaffected. It distinguishes draft-scoped removal from order-level operations, though it never names its natural counterpart (upload_attachment).

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: this is the way to remove an attachment from a draft. The clause 'existing orders stay immutable' implicitly tells the agent this will not help for order-scoped changes, but no explicit when-to-use or when-not-to-use guidance or alternative tool is named.

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 closed-world, so safety is covered and the description does not contradict them. The description adds only that the read targets a prior mutation's result; it says nothing about behavior for an unknown/expired key, whether the response can be a pending state, or how long results are retained.

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 waste, which is structurally good. But it is under-specified rather than appropriately sized: one clause is doing work that two or three should, given the non-obvious parameter contract.

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

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

With no output schema and 0% parameter description coverage, the description is the only documentation channel, and it leaves the return value, pending/error semantics, and both required parameters undefined. Annotations cover the safety profile but not the calling contract.

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 both parameters are bare strings with only length bounds. The description never explains that 'tool' is the name of the mutation tool originally invoked or that 'idempotency_key' is the key captured from that call; only the word 'idempotent' loosely gestures at one parameter. With 0% coverage the description had to compensate and does not.

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

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

States a specific verb+resource: read the result of a previous idempotent mutation. An agent can tell this is a follow-up lookup rather than a mutation itself, and no sibling tool in the list deals with idempotent results, so differentiation is implicit. It stops short of 5 because 'result' is not pinned down (pending vs. final outcome).

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

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

The word 'previous' hints at sequencing (call after a mutation), but there is no explicit when-to-use, no condition under which to skip it, and no named alternative or prerequisite (e.g. 'requires the key returned by the mutation'). The agent must infer the entire calling protocol.

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 idempotent, destructive and openWorld, and the description adds real context on top: the charge is drawn from the prepaid balance at the exact quoted total, and 'queued' explicitly means not printed, mailed or delivered yet. It also explains idempotent-retry mechanics (reuse key/body) and the INSUFFICIENT_FUNDS outcome. It does not say whether a queued order can still be cancelled or reversed, which matters for a destructiveHint 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?

Four tight sentences, front-loaded with the core action, then the queued-vs-delivered caveat, then retry mechanics, then the error path. No filler and nothing repeated from the schema or annotations.

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 destructive, money-spending tool with no output schema, the description covers cost source, delivery semantics, idempotency and one error branch. It still leaves the required identifier chain (send_intent_id → quote_id → proof_id) and the successful response shape undocumented, which an agent needs to call this correctly on the first attempt.

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 7 parameters, so the description must carry the load. It clarifies grant_id (optional, permission fallback), expected_total_minor (must equal the exact final total) and idempotency_key (reuse on retry), but leaves send_intent_id, quote_id, proof_id and the USD const constraint unexplained and their relationships to this call unstated.

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?

Names a specific verb (send) and resource (the letter), then immediately disambiguates the verb's real semantics: it spends the exact final total from the prepaid balance and queues one mailing order. That distinguishes it cleanly from sibling steps quote_for_send, quote, prepare_checkout and create_payment_link, which an agent would otherwise confuse with '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?

Gives clear operating context: grant_id is optional and falls back to the owner's active permission, and the same key/body must be reused on retry. It also prescribes an action on INSUFFICIENT_FUNDS (surface the returned funding link). What it lacks is an explicit statement of what must precede this call (the quote/proof flow) or which sibling to use instead when the user only wants pricing.

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 non-read-only, idempotent, non-destructive, closed-world, but the description adds real value: success does not guarantee the panel rendered, retry must not repeat writes, and content trust rules for PDFs, letter text and draft fields. The only gap is that it never explains what the panel actually shows or whether anything is persisted, which matters given readOnlyHint=false.

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 when-to-use constraint is front-loaded and each sentence carries operational content (retry policy, trust rules). It is a dense paragraph of long compound sentences, and the untrusted-content sentence is broad boilerplate that could be tightened, but there is little outright 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 no output schema the description need not describe return values, and it covers failure recovery and data-trust well. However, for a 2-required-parameter tool with zero schema coverage, it leaves draft_id/version semantics entirely unexplained, so an agent cannot confidently construct the call from this definition 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 0% and the description never mentions the two required parameters. 'This existing result' and 'the same saved draft' loosely imply draft_id addressing, but nothing explains what version means, how it is obtained, or what happens on a stale version.

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 frames the tool as an 'optional inline proof' that is 'never the default writing/review path', which hints at rendering a letter proof but never states plainly that it displays a letter preview from a saved draft. The verb is ambiguous ('show' vs 'render a proof panel'), and it does not name the sibling tools (preview, get_proof, get_draft) it replaces. An agent can infer the display intent but has to guess at the concrete action.

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 an explicit when ('only when the user explicitly requests it') and an explicit when-not ('never the default writing/review path'), which is stronger than most definitions. It also prescribes a fallback path on render failure (panel 'Try again' once, else the review_url) but does not name any sibling tool as the alternative, so routing is by condition rather than by tool name.

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

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

Beyond annotations, the description adds privacy and access constraints: constant, public, official SDK initialization only, and no private data, account, tool, or provider access. It does not explain what 'display' concretely means, but annotations already cover read-only, idempotent, non-destructive, and closed-world 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 two sentences, front-loaded with the action and followed by access constraints. 'Official SDK initialization only' is slightly opaque, but the text is not padded or redundant.

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 tool with an output schema and rich annotations, the description supplies the essential purpose and access exclusions. It still lacks when-to-use context and detail about what the diagnostic displays, but the structured metadata covers most remaining needs.

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 and schema coverage is 100%, so the baseline is 4. The description does not need to add 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 states a specific verb and resource: it displays a public UI diagnostic. It does not name or differentiate a sibling, but no sibling appears to be a diagnostic tool. The phrase 'constant public UI diagnostic' is somewhat vague about what diagnostic is shown.

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, when not to use it, or which sibling to choose instead. The constraints imply a public diagnostic context, but they do not route the agent to this tool or explain the triggering scenario.

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 idempotentHint=false, and the description adds concrete context beyond them: text-only edits replace explicit pages, page IDs stay stable, omitted address fields are preserved, and a fresh proof/quote/approval is required before editing. It does not explain what happens on a stale `version` (conflict/rejection), which is the main behavioral risk for a destructive same-revision edit.

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

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

Front-loaded with the core edit semantics, then the destructive page-replacement rule, then address handling, then preconditions and retry. The telegraphic sentence fragments are dense but each carries a distinct rule, with no filler.

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

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

Given 18 parameters, no output schema and destructive semantics, the description covers editing and addressing well but leaves a required parameter (`version`) unexplained in both schema and description, and gives no signal about the return value or failure modes of a conflicting revision. Adequate but with an important gap for a mutation tool of this complexity.

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

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

Schema description coverage is only 6% across 18 parameters, so the description must compensate and it does so for only part of the surface: pages/page_id preservation, text vs pages, sender/recipient objects vs sender_id/recipient_id, and idempotency_key. It says nothing about `version` (required optimistic-concurrency token), content_type, style, paper, envelope, decorations, or the handwriting configs.

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 ('Edit writing or supported options') on an existing draft in the same revision, which an agent can distinguish from create_draft or get_draft. The phrase 'supported options' is vague and only clarified later by the address/field examples, so the purpose statement is clear but not fully self-contained.

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?

Offers real usage rules: never guess missing details, edits require fresh proof/quote/approval, reuse the same idempotency key on retry. However, it never routes the agent to alternatives (create_draft for new letters, get_draft to read current state, quote_for_send before sending), so the guidance is implied rather than comparative.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, and the description adds genuinely useful context about treating uploaded content as untrusted and preserving PDFs as files rather than recomposing them. But it says nothing about what the upload does to the draft, whether the operation replaces or appends an attachment, or how idempotency_key interacts with the annotation's idempotentHint=false. Notably, much of the text duplicates the schema description of content_policy_acknowledged rather than adding new 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 purpose is front-loaded in the first sentence, which is good. The remaining three sentences are a policy block that is repeated verbatim in the schema's content_policy_acknowledged description, so a meaningful share of the text does not earn 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?

This is a mutation tool with no output schema and near-zero parameter documentation. The definition never explains what a successful upload returns, how version and draft_id scope the write, or what an idempotency_key collision does. For a seven-required-parameter write operation, that is a substantial gap no other structured field fills.

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 14% — six of seven parameters have no description at all. The phrase 'transparent PNG artwork' loosely explains the 'decoration' enum value and 'PDF, photo' maps to the other two kinds, which is a small assist. But draft_id, version, name, content_base64, idempotency_key and the significance of the true-only acknowledgement boolean are left entirely to schema inference.

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 first sentence names a specific verb and resource with scope: 'Upload a non-sensitive print PDF, photo or transparent PNG artwork.' An agent can tell what the tool does. However, it never contrasts itself with siblings like add_library_artwork or remove_attachment, so the boundary with those tools must be inferred from names alone.

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

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

The description is almost entirely a content policy. It states what content is forbidden (medical records, payment-card data) but never says when to choose this tool over add_library_artwork, nor what the prerequisite state of a draft must be before uploading. The agent gets exclusions but no positive routing guidance.

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