PostalForm

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real behavioral value: retry the same checkout/token on interruption and reuse of existing authorized/processing/paid payments, which signals idempotent semantics an agent would not otherwise know.

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 precondition is front-loaded and each sentence carries distinct information (precondition, token type, parameter mapping, retry, reuse). It is slightly dense but has no redundant 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 payment-finalization tool with nested objects and an output schema already present, the description covers the prerequisite, parameter intent, retry/idempotency, and points to the returned status. Return-value details are correctly left to the output schema; only the sibling relationship with pay_order is unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond it: it clarifies that checkout_session_id is the order ID and instructs not to resend the document or addresses, constraining how buyer/payment_data should be populated.

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: pay an existing/prepared checkout session after approval, with the payment token. It is clear what the tool does, though it never names or contrasts with the sibling pay_order, so sibling differentiation is left implicit.

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 precondition (buyer has approved the prepared order and total) and explicit do-nots (do not resend the document or addresses), plus retry guidance. It does not explicitly route the agent away from or toward the sibling pay_order, so it stops short of 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 readOnlyHint=false, destructiveHint=false, openWorldHint=true, and the description adds the crucial non-obvious trait that draft creation never pays and that a downstream call is required. It also describes the two payment-path responses (checkout session vs MPP challenge + PDF preview). It does not disclose idempotency behavior or what happens to the draft if never paid, which is why this is a 4 rather than a 5.

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

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

Three dense sentences, front-loaded with purpose and outputs, then payment paths in order of likelihood. Every sentence carries routing or behavioral information, though the MPP sentence is slightly compressed and the x402 pointer could sit earlier for faster triage.

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 23-parameter, multi-protocol tool with an output schema, this covers the decision-relevant behavior: outputs, non-payment invariant, and the handoff to complete_checkout/pay_order. It omits what a 'supported workflow form' means and how slug, sender/recipient address types, and attachments interact, which a caller must infer.

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 17% across 23 parameters, so the description carries a heavy burden and only partially meets it: it explains payment_protocol=mpp and the buyer_email requirement, which are the highest-consequence parameters. The three required parameters (slug, sender_name, sender_address_type) and the address/attachment/class options get no explanation beyond the schema, so the coverage gap is not fully compensated.

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 ('Prepare a supported workflow form for mailing') and names the key outputs, and it explicitly distinguishes itself from siblings by pointing x402 callers to postalform.create_machine_order. An agent can tell this apart from create_order_draft, create_letter_order_draft and create_machine_order 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?

Gives explicit routing: hosted checkout URL by default, complete_checkout with a Stripe shared payment token after buyer approval, mpp mode via payment_protocol=mpp plus buyer_email followed by postalform.pay_order, and x402 via a different tool. It also states the when-not ('Draft creation never pays') so the agent knows this tool stops short of payment.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the write/safety profile is already covered. The description adds real behavioral context beyond that: 'Draft creation never pays', the exact return payload (order ID, total, hosted checkout URL, checkout session), the MPP challenge/preview behavior, and that signatures may be typed or drawn. It stops short of stating auth requirements or rate limits.

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

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

Front-loaded with the action and the returned artifacts, then the checkout/MPP branches. Every sentence carries routing or behavioral information; the MPP and x402 sentences are dense but each names a distinct flow rather than 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?

For a 20-parameter, nested-object tool with an output schema, the description covers the payment lifecycle, the signature capability, and sibling routing well. The remaining gap is the address-selection parameters and mailing options (mail_class, certified, double_sided), which are left entirely to a sparse schema.

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

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

Schema description coverage is only 15% across 20 parameters, so the description carries a heavy burden. It does clarify payment_protocol and buyer_email and notes that letter text and signatures are supplied inline, but it never explains the Address/Container/Manual address_type enums or how address_id vs address_text vs address_manual differ — the single most ambiguous part of 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 and resource ('Prepare letter text for mailing' returning an order ID), and clearly distinguishes itself from create_pdf_upload ('no PDF upload or browser is needed') and create_machine_order ('For x402, use postalform.create_machine_order'). An agent can route among the sibling draft creators 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?

Explicitly lays out the branches: use complete_checkout after buyer approval with a Stripe shared payment token, otherwise present the hosted checkout URL; set payment_protocol=mpp plus buyer_email for MPP and then call postalform.pay_order; use create_machine_order for x402. When-to-use and which-alternative are both spelled out.

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

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

Annotations already declare openWorldHint=true, readOnlyHint=false, and destructiveHint=false, so the safety profile is partly covered. The description adds non-obvious behavior: payment challenge/retry flow, that the unpaid response carries checkout_url and status_url, buyer-approval gating, and the anti-pattern of recreating orders for payment paths. It stops short of discussing idempotency explicitly (only implied via request_id in the schema) or rate limits.

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

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

The definition is dense and front-loaded, leading with creation scope before enumerating payment and bulk rules. It is longer than ideal and mixes bulk-mode constraints with payment-protocol guidance, but each sentence carries operational content rather than 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-shape explanation is unnecessary, and the description covers the two dominant flows (single-recipient and bulk) plus payment fallbacks. Given 29 parameters and nested objects, it leaves a fair amount of per-field semantics to the schema, but the critical routing and bulk rules are 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?

Schema coverage is only 38% across 29 parameters, so the description must compensate. It usefully explains the bulk exclusivity rule (exactly one of bulk.csv_content or bulk.recipients plus a shared PDF or template) and the 'omit top-level recipient fields' rule, but the many single-recipient options (color, double_sided, mail_class, certified, postcard_size, render/signature details) receive no description-level clarification.

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

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

The description opens with a specific verb and resource set: 'Create a single PDF, letter, workflow-form order, or bulk letter campaign and pay through MPP or x402.' It also names the sibling alternatives it is not (pay_order for bulk MPP, draft + complete_checkout for Stripe SPT), so an agent can distinguish it from the surrounding order tools without opening 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?

It gives explicit routing: use this for machine orders, use postalform.pay_order for bulk MPP retries, use a draft tool plus complete_checkout for Stripe SPT single-recipient clients, and otherwise present the hosted checkout URL. It also states the when-not condition ('never recreate the order to change payment paths') and the no-wallet fallback.

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=false and openWorldHint=true, so the safety profile is partly covered. The description adds the critical behavioral fact that 'Draft creation never pays,' separating this from pay_order/complete_checkout, and describes the MPP challenge/preview response shape. It does not restate idempotency or rate-limit behavior, but request_id idempotency is already documented in the schema.

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

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

Front-loaded with the core verb and return values, then flows through hosted, MPP, and x402 paths in distinct sentences with no filler. Slightly dense — several paths are packed into a single paragraph — but every sentence carries routing information an agent needs.

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

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

For a 21-parameter, nested-object, open-world mutation tool with an output schema, the description supplies everything structured fields cannot: the three payment paths, the post-approval handoff tools, and the explicit assurance that drafting never charges. Return-value detail is present without contradicting 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 100%, so baseline is 3. The description earns above baseline by tying parameters to workflow semantics beyond the schema text: payment_protocol=mpp requires buyer_email and yields a different response (PDF preview, checkout_url fallback, MPP challenge), which the per-parameter schema descriptions only state in isolation.

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

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

States a specific verb and resource ('Prepare an existing PDF for mailing') and immediately names what it returns (order ID, total, hosted checkout URL, checkout session). It also distinguishes itself from siblings by explicitly deferring x402 to postalform.create_machine_order and payment completion to complete_checkout/pay_order.

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 the agent explicit routing conditions: use complete_checkout with a Stripe shared payment token after buyer approval, otherwise present the hosted URL; for MPP set payment_protocol=mpp plus buyer_email and then call postalform.pay_order; for x402 use create_machine_order. When-to-use and when-to-use-something-else are both spelled out.

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

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

Annotations already declare a non-read-only, open-world, non-destructive operation. The description adds useful behavior beyond annotations: short-lived upload URL/token, multipart/form-data with a file field, and client-generated Content-Type boundary.

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

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

Two compact sentences and one multipart instruction, with the usage condition front-loaded. Every sentence adds actionable 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?

Output schema exists, so return values need not be explained in the description. The definition covers when to use it and the multipart mechanics, though it leaves token expiry and authentication details unstated.

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

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

Schema description coverage is 100%, so all four optional parameters are already documented in the schema. The description adds multipart context but no additional parameter-level meaning, so baseline 3 is appropriate.

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

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

States a specific verb and resource: creates a short-lived PDF upload URL and upload token. The upload-specific purpose clearly distinguishes it from sibling order, form, and address 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?

Explicitly says when to use it: when the host cannot provide a PDF file param directly. It gives clear context but does not name exclusions or alternative sibling tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds useful scope context ('supported single-mailpiece' workflow) and content shape, but says nothing about behavior for unsupported slugs or how to obtain valid ones.

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

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

One front-loaded sentence with zero filler; the trigger condition comes first and the payload description follows. Nothing could be trimmed without losing signal.

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 and full annotation coverage, the return shape and safety profile are handled. However, an agent still lacks guidance on where valid slugs come from (presumably list_forms) and on failure behavior for unsupported workflows, which is a real gap for a lookup tool.

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

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

Schema description coverage is 100% with a single documented 'slug' parameter including an example ('8822'), so the baseline is 3. The description marginally reinforces that the slug must resolve to a supported single-mailpiece workflow but adds no syntax or validity detail beyond the schema.

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

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

States a specific verb+resource (get form schema) and scopes it precisely to 'one supported single-mailpiece PostalForm workflow', enumerating what the schema contains (fields, groups, attachments, dependencies). This is clearly distinct from list_forms, though 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?

'Use this when you need a machine-usable schema...' is a when-to-use statement, but it is nearly circular — it restates the tool name. It names no alternative (e.g. list_forms for discovering valid slugs) and gives no when-not or prerequisite guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds genuinely non-obvious behavior: tracking events capped at the latest 50, missing carrier evidence returned as null, and the warning that processing state or a tracking number alone does not prove mailing or delivery. That is semantic context no annotation or schema could 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 sentences, front-loaded with the return payload before the caveats and the negative scope statement. Every clause carries distinct information: field list, bulk-vs-individual routing, null semantics, and the non-action guarantee.

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 a rich output schema (which alone would absolve it of explaining return values), the description still pre-summarizes the payload shape and flags the bulk-order variation and null semantics. For a single-required-param read tool, nothing an agent needs to invoke it correctly is missing.

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

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

Only one parameter (order_id) and schema description coverage is 100%, with format/pattern fully specified in the schema. The description adds nothing about the identifier's syntax or sourcing, so the schema does all the work — the expected baseline of 3.

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

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

Specific verb (read/get) plus a precise enumeration of what is returned: payment, processing, mailing/carrier status, latest 50 tracking events, return-receipt availability, plus bulk-order campaign fields. The closing clause 'does not pay, mail, or acquire receipts' cleanly separates it from siblings like pay_order and the create_* 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?

It routes the agent for a real alternative case ('use the campaign dashboard for individual recipients') and implicitly tells the agent this is the status-check path rather than the pay/mail path. It stops short of an explicit when-to-use/when-not statement with named sibling tools, so it is clear but not exhaustive.

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 safety is fully covered. The description's only added behavioral content is the inclusion/exclusion scope; it says nothing about pagination behavior or result ordering, which are relevant for a catalog listing.

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

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

Two sentences, front-loaded with the use condition and no filler. The phrasing is slightly convoluted ('the published single-mailpiece PostalForm workflow catalog available to agents'), but nothing is gratuitous.

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 a full output schema present, return values need no explanation, and annotations cover the safety profile. The description supplies the scope boundaries an agent needs; only pagination/search semantics are left entirely to the schema, which is acceptable.

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

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

Schema description coverage is 100% — q, limit (including max 200/default 50) and cursor are all documented in the schema. The description adds no syntax, matching behavior, or format detail beyond that, so the baseline of 3 applies.

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

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

The description identifies the resource precisely as the published single-mailpiece PostalForm workflow catalog and scopes it to what agents can use. It stops short of a clean verb+resource statement (it never literally says 'lists forms') and only distinguishes itself from siblings via scope language rather than by naming a competing tool.

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

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

The opening 'Use this when you need...' gives a clear use condition, and the exclusion of coordinated statutory multi-recipient workflows tells the agent when NOT to use it. It does not, however, name an alternative tool (e.g. get_form_schema) that would serve the excluded case.

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 say readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the write/open-world nature is already declared. The description adds genuinely new behavioral context beyond that: without payment_authorization it only returns a challenge, with it, it can pay and send real mail, and no document or addresses are resubmitted. It notably reveals a real-world mailing side effect not captured by destructiveHint=false, though it does not spell out idempotency or permissions in depth.

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?

Six sentences, front-loaded with purpose then usage then behavior. Most sentences carry distinct value, but it is somewhat dense and a sentence like 'Review the preview or campaign_url, recipient count and total' mixes in output detail that could be trimmed.

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 enumerated, and the description still points to the returned payment status. Combined with clear inputs, prerequisites, retry behavior, and the challenge-vs-pay distinction, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is only 50%: payment_authorization is documented in the schema, but order_id has no schema description. The description compensates by explaining where order_id comes from (draft tools with payment_protocol=mpp, or create_machine_order) and that it should be reused verbatim on retries. That adds real meaning beyond the UUID format constraints.

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 (pay) and resource (existing MPP order across PDF, letter, form, or bulk campaign), plus the prerequisite (buyer approval) and the challenge-only mode. It also names the sibling create_machine_order, so an agent can distinguish it from the draft-creation tools 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?

Explicitly says to use the order_id returned by any draft tool with payment_protocol=mpp or by create_machine_order, and gives the exact procedure when switching from create_machine_order (omit the credential first to obtain this endpoint's challenge). Retry guidance is also given. Nothing about when/when-not is left 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety and side-effect profile is fully covered. The description adds only the purpose framing, not extra behavioral detail such as latency, failure semantics, or what a 'unreachable' result looks like. Adequate but adds little 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?

A single front-loaded sentence with the usage condition first and zero filler. Every word earns its place for a tool this simple.

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 no-parameter health-check tool with full annotation coverage and an output schema that already describes the return value, the description contains everything the agent needs to select and call 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?

The tool takes zero parameters, so there is nothing for the description to document beyond what the schema already shows. 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?

The description states a clear purpose: verifying that the PostalForm MCP server is reachable via a quick health check. The resource (server reachability) is specific and naturally distinct from all order/form siblings. It stops short of explicitly naming a sibling or contrasting itself, but no contrast is really needed here.

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 triggering condition ('when you want a quick health check that the server is reachable'), which tells the agent the context for calling it. There is no when-not guidance or mention of alternatives, but for a ping tool no alternative is plausible.

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, non-destructive, and closed-world behavior. The description adds useful behavioral detail beyond annotations: it renders the letter, validates addresses, and returns a widget with a create-draft action. It does not cover permissions or rate limits, but those are less critical for a read-only preview.

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

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

Two sentences, front-loaded with the primary action and purpose. Every clause adds information and 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?

For a tool with 17 parameters, nested objects, and no schema descriptions, the description is too sparse. It explains the high-level preview behavior but leaves the agent with little guidance on how to construct the complex address and letter payloads, even though an output schema exists to cover return values.

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 17 parameters, many with nested objects and enums. The description only generically references 'letter' and 'addresses' and does not explain required fields such as sender_address_type, recipient_address_type, address ID/text/manual variants, request_id, mail_class, or render options.

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 ('preview'), resource ('letter order draft'), and distinguishes the operation as non-writing. It does not explicitly name sibling tools like create_letter_order_draft, but the preview framing and 'before creating checkout' timing make the purpose 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?

It gives clear timing: use this before creating checkout to prepare a non-writing preview. It does not explicitly say when not to use it or name alternative sibling tools, but the context is sufficient to infer that this is a pre-creation validation step.

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 correctly spends its words on behavior annotations cannot express: the two-phase Container → Address drill-down workflow, the US default for country_code, and which result types are order-eligible. It does not add rate-limit, auth, or result-count context, which keeps it short of a 5.

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

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

Three dense sentences, front-loaded with the core action and return shape, then the filtering detail, then the drill-down rule. No restatement of the name 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?

With an output schema present and full parameter documentation, the description only needs to cover what structured fields cannot: the multi-step container drill-down and result-type validity. Both are stated, leaving nothing an agent needs in order to call and chain this tool 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 coverage is 100%, so a 3 is the baseline and the schema already documents all four parameters. The description goes further by explaining how container and query interact across successive calls and by reinforcing the country_code default, adding cross-call meaning the schema cannot convey; target is left 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 and resource ('search for a mailing address') plus the concrete return payload ('Loqate suggestions with IDs'). An agent can immediately distinguish this lookup tool from the sibling order-creation tools (create_order_draft, pay_order, etc.).

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?

Explicit when-to-use and follow-up routing: pass country_code to filter, and if a suggestion has type 'Container', call this tool again with container=<id> to drill down. It also states the terminal constraint that only type 'Address' is valid for order creation, telling the agent when a result is usable and when it is not.

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