DirectMailAmerica — Narrow

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

Beyond the readOnlyHint/idempotentHint annotations, it discloses the decoded size ceiling, that output is an embedded PDF with resolution warnings, that nothing is persisted or mailed, and that workspace auth is required. These are exactly the side-effect and constraint facts an agent needs and none are in the schema or 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?

Front-loads the core action and limits, then layers constraints; most sentences earn their place. The telegraphic final clauses ('No external URL fetch, persistence or mailing') are compact to the point of terseness but still informative.

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

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

An output schema exists so return values need not be explained, yet the description still summarizes them (embedded PDF, warnings). Size, auth, and side-effect posture are all covered; the only real gap is the unmapped format enum, which matters for a tool whose whole job is format-sensitive fitting.

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. It does well for imageBase64 (converted from a raw char limit to a 'maximum 25 MiB decoded' semantic) but only gestures at format via 'small single-sided front, large double-sided front and reverse artwork area' without mapping these to the enum values custom_postcard / pro_postcard_85x55 / postcard_reverse.

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 ('Convert imageBase64 ... to print-ready PDF') and adds the mechanism (website's fitting, orientation and resolution checks). No sibling tool performs conversion or rendering of artwork, so the boundary is 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?

Gives clear context for when to use it ('print-ready PDF', fitting/orientation/resolution checks) and useful exclusions ('No external URL fetch, persistence or mailing'), plus the 'Workspace authentication required' precondition. It stops short of naming a sibling alternative or explicitly saying when not to use it, so it is not 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 read-only, idempotent, non-destructive, closed-world behavior. The description adds meaningful traits beyond annotations: no charge, workspace authentication required, embedded private resource delivery, and a security warning to treat document content as untrusted data.

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

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

The purpose is front-loaded in the first sentence, followed by concise operational details. Every sentence earns its place by covering billing, security, and authentication without wasting words.

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

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

The description is sufficient for a simple read-only tool with an output schema and rich annotations. It covers billing, authentication, and security, though it could more explicitly explain the 'id' parameter's origin, such as retrieving it from list_jobs.

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 schema has 0% description coverage for the single required 'id' parameter. The description implies 'id' refers to an owned job, which adds some meaning, but it does not explicitly document what the ID identifies or where to obtain it.

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: downloading an owned job's saved print PDF. It also names the file type, delivery form (embedded private resource), and edge case (Email to Letter document recovery), making it clearly distinguishable from siblings like list_jobs or preview_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 context is clear: use this for an owned job's saved print PDF, including recovery scenarios. It does not explicitly name alternatives or when-not-to-use conditions, but the prerequisite 'owned job' and 'Workspace authentication required' give adequate selection 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 readOnly/idempotent/non-destructive/closed-world, so the description is not obligated to restate safety. It adds value with the auth requirement and the pagination behavior, plus a clear negative statement that no payment is initiated.

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, zero filler, with the core read action and returned data front-loaded before the exclusions and auth note.

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

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

An output schema exists, so return shape needn't be explained, and the auth prerequisite is stated. The only real gap is cursor semantics for `before`, which an agent needs to page backwards correctly.

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

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

Schema description coverage is 0% across two parameters, so the description must carry the meaning. It only says "pagination", which hints that both params are paging controls but never explains that `before` is an opaque `timestamp|id` cursor or that limit defaults to 25 and caps at 100.

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 the workspace credit ledger — and enumerates what the ledger contains (amounts, balances, order references, pagination). It implicitly separates itself from get_credits by framing this as historical ledger reading, though it never names that sibling.

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

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

"Does not fund an account or initiate payment" explicitly rules out the write/payment siblings, which is real when-not guidance. What's missing is a positive rule for choosing this over get_credits (current balance) versus this ledger history.

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 safety bar is low. The description adds genuinely non-schema context: anonymous checks leak no private workspace data, and the status call triggers no charge, mailing, funding movement or credential disclosure. That is meaningful side-effect disclosure beyond the annotations, though the phrasing is compressed and slightly ambiguous.

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

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

Three short sentences, front-loaded with the core purpose before the privacy and no-side-effect caveats. Every clause carries information, though the final 'No charge, mailing, funding or credential disclosure' is telegraphic and takes a moment to parse.

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

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

With an output schema present, the description need not explain return values, and it correctly focuses on scope of checks plus privacy/side-effect guarantees. For a zero-parameter, read-only probe, this covers what an agent needs; only the lack of explicit use-case routing keeps it from full marks.

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?

Zero parameters, so baseline is 4. The description still adds framing by naming the facets returned (principal, environment, scopes, permissions), which helps an agent understand what the empty-argument call yields, without re-describing schema fields.

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 (verify) and resource (this mcp-narrow connection) and enumerates what is surfaced: workspace principal, environment, scopes, tool permissions. The name and title are restated rather than differentiated, but the enumeration of checked facets makes the tool's purpose unmistakable and distinct from the other read-ish siblings like get_workspace_settings.

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 – 'Anonymous checks reveal no private workspace data' hints it can be called pre-auth, but the description never says when to call this versus get_workspace_settings or get_credits, nor when it should be avoided. No explicit alternatives or prerequisites are 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 this as read-only, idempotent, non-destructive, and closed-world. The description reinforces that safety profile with 'No charge or balance change' and explicitly excludes purchase/checkout/transfer operations, adding useful confirmation beyond structured fields.

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 the core read action and followed by safety exclusions. Every sentence earns its place without repetition or filler.

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

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

Given zero parameters, rich annotations, and an output schema, the description provides everything needed: what is read, the unit (USD cents), and explicit confirmation that no mutation occurs.

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 has no parameter semantics to explain. The description appropriately avoids unnecessary parameter detail and correctly implies no input is required.

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 the authenticated workspace's existing balance in USD cents. It clearly distinguishes this from purchasing, checkout, or transfer operations, so an agent can identify the tool's scope without opening the schema.

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

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

It gives clear usage context and explicitly rules out purchasing credits, initiating checkout, or transferring funds. However, it does not name sibling alternatives such as get_billing_history or get_pricing for related financial data.

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 the description adds genuinely new behavior: no charge or submission occurs, completed quotes are terminal, access is scoped to account/endpoint/environment, and guest IDs are bearer capabilities. The guest-ID sentence is a bit cryptic and its relation to quoteId is left implicit.

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?

Five short sentences, front-loaded with what is read and what is returned. The final two sentences are terse to the point of being under-explained, but no sentence is filler.

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

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

An output schema exists, so return values need not be spelled out, and the safety profile is covered by annotations. What remains covered is the charge/submission guarantee and terminal-state rule; only the quoteId origin is missing.

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

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

Schema coverage is 0% for the single required quoteId, so the description must carry the load. It gestures at identifier semantics ('Guest IDs are private bearer capabilities', access bound to account/endpoint/environment) but never says what quoteId is or where to obtain it, leaving a real gap.

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

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

States a specific verb and resource ('Read a saved standard-mail quote') and even enumerates what is returned (exact PDF and send outcome). It does not explicitly contrast itself with siblings like quote_letter or send_letter, but the read-of-saved-quote framing is 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?

'Use after interruption' gives a concrete triggering situation, and 'completed quotes cannot be sent again' tells the agent a hard precondition on downstream action. No sibling is named as an alternative, so it stops short of full 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?

Beyond the annotations, the description discloses billing impact ('No charge'), authentication requirements ('OAuth or a key for the owning workspace'), data freshness limits ('Does not itself refresh mailing status'), and error handling guidance ('Inspect the body for not_found'). These are substantive behavioral traits an agent needs before invoking the tool.

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

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

The description is front-loaded and compact, with each short sentence adding practical information: billing, read behavior, freshness limitation, and error inspection. There is 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 a simple one-parameter read tool, rich annotations, and an output schema, the description covers authentication, billing, staleness, and not-found handling well. The main missing piece is clarity about the 'id' parameter itself, which prevents a full 5.

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 schema has 0% description coverage for the single required 'id' parameter, so the description must carry the burden. It only says lookup is 'by id' and does not clarify whether this is a job id, letter id, tracking id, or its expected format, leaving meaningful ambiguity.

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 stored job status and tracking by id. It is clearly more than a tautology, but it does not explicitly differentiate this lookup-by-id tool from siblings such as list_jobs or download_job_document.

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 clear usage context by specifying lookup by id and warning that the tool does not itself refresh mailing status. It does not name alternatives or state a full when-not-to-use rule, so it falls short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description clears the lower bar by adding real context: no charge or account needed, and authenticated calls additionally return workspace balance. The explicit non-side-effect list (no send, no checkout, no funding) is the kind of detail 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?

Three short sentences, front-loaded with the core action and followed by the auth/side-effect constraints. Slight redundancy between "no account or charge required" and "fund an account", but nothing 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?

The output schema exists, so return values need not be described, and the auth/no-charge semantics are well covered. What is missing is a routing rule against the crowded quote siblings and any guidance on the three undocumented boolean parameters, which for a zero-required-parameter tool leaves notable ambiguity.

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% – just couponCode is documented – so the description must carry the load, and it names mail class, page count, recipient count, print options and coupon. That leaves color, certified and electronicReturnReceipt only vaguely covered by "print options", with no units, defaults or interaction between mailClass and certified explained.

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

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

Opens with a specific verb+resource ("Calculate a public USD physical-mail quote") and enumerates the inputs that drive the price. It does not, however, distinguish itself from the many pricing siblings (get_letter_quote, get_product_quote, quote_letter, quote_product), which the agent must disambiguate alone.

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

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

"No account or charge required" and "A quote does not send mail, initiate checkout or fund an account" give useful inclusion and exclusion context. But with four sibling quote tools, no sentence tells the agent when this generic physical-mail quote is preferred over get_letter_quote or quote_product.

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, closed-world behavior, so the safety profile is covered. The description adds genuinely useful context—'No charge' (distinguishing it from billable quote/pricing tools) and the exclusion of coupon books—but says nothing about response shape or freshness of the catalog.

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 most decision-relevant fact ('No charge', 'Public'), which is good. But it is a series of choppy fragments, and the specific postcard-size example and 'reverse inputs' phrasing read as catalog trivia rather than selection-critical 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?

With an output schema present, return values need no explanation, and annotations cover the safety profile. The description supplies the missing pieces—cost, accessibility, and what the catalog covers—so the definition is adequate for a zero-parameter read tool.

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

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

The tool takes zero parameters, so the baseline is 4; omitting any argument discussion is correct here and the description does not mislead about 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?

Clear verb+resource: retrieves the full product catalog, and it hints at what the catalog contains (PDF dimensions, stocks, return envelopes). It does not name a sibling directly, but the line 'Products require an exact quote' implicitly separates it from get_product_quote/get_pricing.

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

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

'No charge' and 'Products require an exact quote' imply this is a free browse step before quoting, and 'Coupon books are excluded' states a scope boundary. However, no explicit 'use this when / use X instead' routing is given relative to get_pricing or get_product_quote.

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 readOnly/idempotent/non-destructive/closed-world, so the bar is low, yet the description still adds an auth prerequisite ('Workspace authentication required') and the idempotent retry pattern for pending results. It adds real context rather than restating the 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?

Four tight sentences with the core action and payload front-loaded, followed by exclusions, retry semantics and the auth prerequisite. No filler and every clause carries distinct information.

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

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

An output schema exists so return values needn't be spelled out, and the description still characterizes what comes back. For a single-parameter read-only tool, auth requirement plus side-effect exclusions plus retry guidance is 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?

With schema coverage at 0% for the single `id` parameter, the description is the only verbal source, and it only implies the value is a quote ID reusable across retries. The pattern/length constraints live in the schema but the description never clarifies where the ID comes from (e.g. quote_product output).

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

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

Specific verb ('Recover') plus resource ('owned saved product quote') plus the exact payload returned ('options, price, expiry and order state'). The word 'saved'/'owned' implicitly separates it from quote_product, preview_product_quote and send_product_quote in the sibling list, so an agent can route without opening a schema.

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

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

'Does not send, charge, renew or replace a quote' explicitly excludes the adjacent write tools, and 'Reconcile pending results using the same quote ID' gives a concrete usage pattern. It stops short of naming the alternative sibling to use for the excluded actions, so 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 readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: an explicit negative guarantee ('Never returns credentials or webhook signing secrets') and the authentication requirement, both of which an agent cannot infer from structured fields. It stops short of noting whether the response can be empty or partial for an unconfigured workspace.

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, then the security caveat, then the auth requirement — a sensible ordering. The middle clause listing downstream features is the only sentence that does not clearly earn its place, since it reads as marketing rather than guidance.

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

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

An output schema exists, so return structure need not be described, and the description covers the two things the schema cannot: auth prerequisite and the exclusion of secrets. For a zero-parameter read tool this is close to complete; only the failure/empty-state behavior for an unconfigured workspace is unaddressed.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly does not invent parameters or imply filtering options that do not exist.

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?

Opens with a specific verb ('Read') and enumerates the exact fields returned (profile name, workspace name, default sender, website links), so an agent knows precisely what this yields. The trailing clause ('for account security, member invitations and API-key management') blurs the line between returned data and use case, slightly muddying an otherwise crisp purpose. No sibling in the list overlaps this resource, so differentiation is not a problem.

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?

States the prerequisite 'Workspace authentication required', which is genuine usage context. However, it never says when to reach for this tool versus other read tools (e.g. get_connection_status, get_billing_history) or what to do if authentication is missing. Usage is implied rather than directed.

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 the description goes beyond them by disclosing the authentication requirement, that pagination is bounded, and what the result is useful for (saved IDs for default-sender selection). It adds real context rather than repeating the safety 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?

Short and front-loaded, which is good, but it is a run of clipped fragments ('Use nextCursor as before', 'No mailing') whose meaning depends on unspecified prior context. Brevity here costs clarity rather than earning its place.

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

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

An output schema exists so return values needn't be spelled out, and the auth requirement is disclosed. But for a tool with three undocumented parameters and a cursor whose name doesn't match the description, the definition leaves too much for the agent to infer before calling it correctly.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely doesn't: limit, search, and before are never explained. Worse, it instructs 'Use nextCursor as before' while the actual parameter is named 'before', so the guidance mismatches the schema and can actively mislead an agent wiring up pagination.

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

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

States a specific verb and resource ('List or search the workspace address book') and bounds the operation ('with bounded pagination'), which separates it from validate_address among siblings. The remaining scope notes ('No mailing') reinforce it but the phrasing is fragmentary rather than a clean statement.

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

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

'No mailing' implies a when-not, and 'Returns saved IDs for default-sender selection' hints at the downstream use case. However, no sibling is named and there's no explicit statement of when to choose this over validate_address or list_cover_sheets, so selection guidance is only implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds information annotations cannot convey: no charge and workspace authentication required, plus the reassurance that the read never mutates saved presets. Minor gap: nothing about result ordering or version selection.

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 in the first sentence, followed by reset guidance, then workflow routing, then cost and auth in short clauses. Every sentence carries distinct actionable content with no 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?

Output schema exists, so return-shape explanation is unnecessary, and the description still flags the key field (defaultDesign) and its meaning. Auth and cost requirements, which no schema or annotation covers, are both stated, making the definition self-sufficient for a no-param read.

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?

Zero-parameter tool, so the baseline is 4; there are no inputs to misinterpret. The description correctly implies the call is unfiltered and lists what the output contains, which is the only parameter-like semantic available.

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

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

Specific verb (List) plus a precise resource (reusable workspace cover-sheet designs and versions) with an explicit extra return field (defaultDesign). It distinguishes itself from the neighboring render_cover_sheet and save_cover_sheet by naming them and their roles.

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 concrete routing: use defaultDesign to reset a local draft, render to preview before saving, and call save_cover_sheet only when the user wants persistence. It stops short of stating when this tool is unnecessary (e.g., if the caller already holds a design), so it is clear context rather than full when/when-not coverage.

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 bar is lower. The description adds genuinely useful context not in annotations: 'No charge' (cost) and the return shape split between structuredContent and text content for older clients. It still doesn't mention rate limits or auth specifics beyond 'authenticated workspace.'

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 dense, front-loaded sentences with zero waste; the cost note leads. The structuredContent/text-content clause is useful but slightly implementation-leaning.

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

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

An output schema exists, so return values need not be explained, and the description still sketches them briefly. Given a simple 2-param read tool, what an agent needs to call it is present; only explicit alternative-selection guidance is missing.

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

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

With 50% schema description coverage, the description restates limit's default/maximum (already in the schema as default/maximum/minimum) and repeats the before cursor semantics already documented in the schema. It clarifies the pagination flow but adds little meaning beyond what the structured fields provide.

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

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

States a specific verb and resource ('List recent jobs in the authenticated workspace') with scope qualifiers. It doesn't explicitly contrast with siblings like get_letter_status or get_billing_history, but the resource is unambiguous enough that an agent can tell it apart.

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

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

Provides pagination guidance ('Pass the last returned job id as before to continue') and scopes to the authenticated workspace, which implies usage. However, it never states when to use this versus alternatives or any exclusions, so the when-to-use criteria are only implied.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: no credits are reserved, no artwork is uploaded, workspace authentication is required, postcards default to full color while letters default to B&W, and composed previews use the first recipient. The postcard proof vs artwork distinction is a non-obvious side effect that would otherwise surprise an agent.

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 core purpose and the body-vs-PDF constraint are front-loaded, and most sentences carry actionable content. It runs long and the postcard proof paragraph is dense, plus a trailing contract URL, so it is efficient but not maximally tight.

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

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

For an 11-parameter tool with an output schema, the description covers the hard parts an agent would otherwise get wrong: input mode exclusivity, color defaults by mail class, proof-vs-artwork handling, authentication, and the instruction to re-check price. Return values are covered by the output schema, so nothing critical is missing.

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

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

With 0% schema description coverage, the description carries the load: it states that exactly one of a plain-text body or a PDF must be supplied (mutual exclusivity the schema does not encode via oneOf), enumerates the feature flags (Certified, electronic return receipt, color, duplex, coupon, bulk recipients), and explains that only the first recipient is used for composed previews. It leaves filename and the from/recipients field shape undocumented, but those follow from 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?

Opening sentence states a specific compound verb (render/inspect and calculate price) over a specific resource (letter or small postcard PDF) and immediately delimits scope with 'without sending, reserving credits or uploading artwork'. This clearly separates it from send_letter and the quote siblings.

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

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

Gives a clear when-to-use context (preview before send, recheck final price before sending) and an explicit when-not (do not send the proof, only the original artwork or body). It never names the alternative pricing/preview siblings, so an agent must infer preview_letter vs get_letter_quote on its own.

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, destructiveHint=false, and openWorldHint=false, but the description adds meaningful behavior: workspace authentication is required, postage placement may vary, postcard previews include the recipient's illustrative address side, and other products return stored artwork. These details go beyond the annotations and help the agent understand side effects and output characteristics.

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

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

The description is front-loaded with the core action and then adds only relevant qualifiers about product-specific preview behavior, safety, and authentication. Each sentence contributes useful information without padding.

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

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

An output schema exists, so return values do not need description coverage. The description adequately covers authentication, read-only behavior, preview semantics, and the relationship to sending, but it leaves a notable gap around parameter semantics for id and recipient.

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 both parameters. It only vaguely refers to a selected recipient in the context of postcard artwork and never explains that recipient is an integer index with default 0 and range 0-99, nor does it describe the required quote id parameter.

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

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

The description states a specific verb and resource: downloading a saved quote's exact artwork PDF. It distinguishes the preview from send_product_quote by explicitly positioning it as a review step before sending, so an agent can identify its role without opening the schema.

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

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

It gives clear usage context: use this to review artwork before calling send_product_quote, and notes that reading never changes the quote or purchases postage. It does not explicitly compare with get_product_quote, but the primary when-to-use condition 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?

Adds substantial context beyond the annotations: the 30-minute quote lifetime, that the PDF proof is an exact proof, that approval is bound to content and must be re-obtained after edits, and that full-profile guest quote IDs act as private bearer capabilities. These are non-obvious security and lifecycle behaviors an agent cannot infer from readOnlyHint/destructiveHint/idempotentHint.

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 dense sentences, front-loaded with the action and scope, then the send_letter contract, then the re-quote rule and the security note. Every sentence carries information, though the send_letter sentence packs several constraints into one run-on clause.

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

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

An output schema exists so return values need no explanation, and the mutation/approval lifecycle is well covered. For a 12-parameter tool with nested address objects and pricing side effects, however, the description leaves the pricing drivers (certified, doubleSided, color, couponCode interactions) and validation failure modes unexplained.

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 42%, so the description must compensate, but it only names categories ('artwork, sender, every recipient, options, expiry and total') without explaining any. Undocumented parameters such as mailClass (the one enum), certified, doubleSided, and electronicReturnReceipt carry cost and eligibility implications that go unaddressed—notably that 'certified' overlaps with the enum value 'certified'.

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?

Opens with a specific verb+resource: 'Create a saved 30-minute standard-letter or Express-postcard quote and exact PDF proof'. The scope (no charge, no send) separates it cleanly from send_letter and from the get_letter_quote/preview_letter siblings.

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

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

Establishes the workflow: this must precede send_letter, which requires this quoteId, confirmed:true, matching approvedTotalCents and an idempotencyKey, and changed content forces a re-quote. Clear when-to-use context, but it never explicitly contrasts with preview_letter, get_letter_quote, or quote_product, so the sibling routing is only implied.

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

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

Strong disclosure beyond the annotations: a third-party upload to DirectMailAmerica for live pricing, no charge or mailing despite destructiveHint=true, a 36-hour hold with expiresAt, a 25 MiB artwork cap, and staging quotes being demo estimates. What is missing is failure behavior (what happens when a page fails the dimension check, whether a quote record persists) and any auth/workspace-key requirement detail.

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

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

Front-loaded with the core purpose and the expiration contract before descending into postcard minutiae, and the approval warning closes it well. It is dense and semicolon-heavy, with the two-sided postcard rule stated twice (once in prose, once again in the schema), costing a little tightness.

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

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

For a 12-parameter, nested-object, mutation-shaped tool, the description covers the hard-to-guess parts (artwork dimensions, double-sided assembly, size limits, demo-vs-live quotes) and an output schema covers the return value. The gap is the untouched optional parameters (envelope, return receipt, paper) that an agent may need to set for a correct quote.

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 only 33% schema coverage, the description does real work: it explains the productId dimension constraint, the doubleSided + pro_postcard_85x55 combination, the reverseMessage OR reverseArtworkBase64 exclusivity, and the combined size limit. Still, several parameters — returnEnvelope, electronicReturnReceipt, paper, filename — are left undocumented in both schema and description, so the compensation is incomplete.

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 names a specific verb (hold a quote), the exact resource (expanded-product quote), the constraints (workspace key, print-ready PDF, 1–100 US recipients) and the outcome (expiresAt). The contrast with siblings is explicit enough: 'no charge or mailing' plus 'before sending' clearly separates it from send_product_quote, and the artwork/pricing language separates it from get_product_quote.

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?

'Obtain approval of artwork, addresses and total before sending' positions this as a pre-send step, and 'Staging quotes are demo estimates' tells the agent the quote is non-binding. However, it never names an alternative tool (preview_product_quote, get_product_quote, quote_letter) or states when a different quoting path should be used, so the agent must infer the choice from sibling names.

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 substantial behavioral context beyond the annotations: fixed address windows, rejection of overflow and unsupported text, no persistence or mailing, and an embedded private PDF return. It also adds the workspace authentication requirement, which is operationally important and not in 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-loaded: the main action comes first, followed by side-effect exclusions, validation behavior, return behavior, and authentication. Every sentence adds useful information without 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?

The schema is rich and the output schema covers the return value, while the annotations cover safety. The description still provides valuable operational context such as validation failures and authentication, though the lack of parameter-level explanation leaves a gap for such a deeply nested input.

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 the full burden of explaining parameters. It only names the top-level inputs as 'design, sender and recipient' and adds that overflow and unsupported text are rejected, but it does not explain the nested address fields, US-only country constraint, state/postal formats, or design field 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: render a one-page letter-size cover-sheet PDF. It also distinguishes this from saving and mailing, which are likely sibling behaviors, so an agent can identify the intended operation without inspecting the schema.

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

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

The description clearly sets boundaries with 'No save or mailing' and notes that workspace authentication is required. It does not explicitly name save_cover_sheet or other alternatives, but the exclusions give sufficiently clear usage context.

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

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

Annotations declare readOnly=false, destructive=true, but the description supplies the operational detail annotations cannot: optimistic-concurrency failure on stale version, the 25-design ceiling, fit validation, preservation of fixed envelope address windows, and the explicit statement that no charge/mailing occurs and existing PDFs or saved quotes are untouched. Auth requirements and the reviewer-workspace carve-out are also disclosed. The destructive framing is consistent with an overwrite-on-update save.

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 purpose and sequencing, then constraints, then side effects — a sensible ordering with almost no filler. It is dense and somewhat run-on in the second half, and the trailing "Workspace authentication required" restates the OAuth sentence just before it.

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, versioned write with a nested design object and an output schema, the description covers what an agent needs: prerequisites, sequencing, failure mode, limits, and the blast radius of the write. Return shape is delegated to the output schema, which is appropriate.

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 carries the load and mostly does: it names every field, explains the id format (64-char lowercase hex) and the create-vs-edit semantics of version, and notes that an empty heading or message simply omits that element. One flaw: it tells the agent to "use defaultDesign to reset a draft," but no defaultDesign property exists in the schema, which has additionalProperties=false — a dangling reference that could mislead.

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?

Opens with a specific verb+resource: "Create or update a reusable workspace cover sheet," then enumerates the editable fields (heading, message, font, sizes, alignment). The reader can immediately distinguish it from list_cover_sheets (read) and render_cover_sheet (preview) because the description names both siblings in the next sentence.

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

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

Gives explicit workflow order: read list_cover_sheets first, preview with render_cover_sheet, then save. It also states the exact create-vs-edit selection rule (new 64-char hex id with version:0 to create; existing id with current version to edit) and the recovery path when a stale version fails.

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, it discloses critical behavior: the tool immediately spends the approved amount, can buy postage, sends nothing on insufficient balance, and staging prevents postage while still debiting the workspace balance. It also explains retry and reconciliation behavior for interrupted or uncertain sends.

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

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

The description is front-loaded with the core action and then covers preconditions, financial effects, failure modes, and retry guidance. It is dense and somewhat run-on, but the information is largely necessary for a destructive financial 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 complex destructive tool with 16 parameters, an output schema, and annotations, the description covers the essential decision context: authentication requirement, quote dependency, approval semantics, spend behavior, staging behavior, and reconciliation after uncertain sends. Return-value details are appropriately left to the 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?

Schema coverage is 56%, and the description adds important meaning for the four required parameters: quoteId must come from quote_letter, confirmed must reflect explicit user approval, approvedTotalCents must match server calculation, and idempotencyKey must be generated once and reused for identical retries. It does not explain every optional parameter, but it compensates for the core high-risk 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 identifies the exact action: releasing an immutable quoteId from quote_letter to send a letter using workspace balance. It clearly distinguishes this from the quoting sibling by requiring a saved quote, confirmed approval, and matching approvedTotalCents.

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 states explicit preconditions: confirmed=true, approvedTotalCents must match the saved quote, and an idempotencyKey must be used after reviewing the exact saved PDF, addresses, and options. It also gives when-not guidance such as changed content requiring a new quote and no guest payment, funding, or cryptocurrency settlement.

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?

Adds substantial context beyond the annotations: it can spend the workspace balance and buy real postage, insufficient balance stops submission, staging never mails, retries must reuse the same saved quote ID, and an 'authorizing'/'needs_review' response requires reconciliation. This is exactly the financial and side-effect detail an agent needs before an irreversible spend.

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

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

Front-loads the core action and gate in the first sentence, then layers constraints. It is a dense run-on paragraph where short sentences would read better, but no sentence is 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?

With an output schema present, return values need no explanation, and the description already covers spend risk, idempotency, credential requirements, and failure modes. Nothing an agent needs in order to safely invoke this destructive tool is missing.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: 'confirmed=true' is explained as the approval gate, and the required 'id' is identified as the saved quote ID to reuse on retry. It does not state the ID format or where to obtain it, leaving a small gap.

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

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

States a specific verb and resource ('Release an immutable saved physical-mail quote') and characterizes the quote as saved/immutable, which cleanly separates it from the sibling quoting/getting tools (quote_product, preview_product_quote, get_product_quote). An agent can tell this is the terminal send step rather than a quoting or preview step.

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

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

Gives explicit preconditions ('Requires approval of the exact artwork, addresses, options and saved total', confirmed=true) and states what is out of scope ('No funding or checkout'). It does not name a specific sibling alternative to use for quoting or previewing, so routing to the alternative is implied rather than explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's added value is the non-goals and the workspace authentication requirement — real context an agent needs before calling. The normalization behavior is named but not characterized (what gets corrected, whether input is echoed).

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

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

Four short sentences, front-loaded with purpose followed by scope limits. Nothing is repeated from the title, though the fragment 'No persistence or mailing' is clipped to the point of being slightly under-specified.

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

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

With an output schema, annotations, and a single nested parameter, the description covers the essentials: what it does, what it doesn't do, and the auth prerequisite. Only the relationship to the surrounding address/letter workflow (validate before send_letter, list_addresses for stored records) is absent.

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

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

Schema coverage is 0%, so the description must compensate; it only partly does. The 'U.S.' framing explains the country const 'US' and the formality of the constraints, but the required nested fields (name, line1, city, state, postal) and their patterns (2-letter state, ZIP or ZIP+4) are left entirely to the schema.

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

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

States a specific verb ('check and normalize') and resource ('U.S. postal address formatting'), and explicitly bounds the scope by ruling out deliverability/verification. It does not relate itself to any sibling (e.g. list_addresses or send_letter), so an agent must infer placement in the workflow.

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 built from exclusions (not verification, no persistence, no mailing) rather than positive usage guidance; there is no 'use this before send_letter' or 'use list_addresses to read stored addresses instead.' The prohibitions do implicitly tell the agent when NOT to use it, which is more than nothing.

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