PostalForm

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

Annotations only declare the write/safety profile, so the description earns credit for adding real behavior: idempotent retry with the same checkout and token, reuse of existing authorized/processing/paid payments, and instruction to follow the returned status and messages. It does not discuss auth requirements, rate limits, or failure modes beyond interruption.

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, all of which carry actionable information, with the preconditions and identifier mapping front-loaded. No filler, though the sentences are long enough that key constraints compete for attention.

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

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

For a write tool with nested objects and an output schema, the description covers preconditions, idempotency, reuse of existing payments, and where to read the outcome. What remains thin is the distinction from sibling payment tools, which the description never addresses.

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, but the description adds genuine meaning: it maps the order ID onto checkout_session_id, states a shared payment token (spt_...) is acceptable, and warns against resending the document or addresses. It does not further clarify the nested buyer/billing_address shapes, which the schema already covers.

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/finalize an already-prepared checkout session with a payment token. It clearly scopes the tool to the post-approval step, though it never names the sibling pay_order it must be distinguished from. Minor ambiguity in 'Pass the order ID as checkout_session_id' blurs resource naming slightly.

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

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

Gives a clear triggering condition ('after the buyer approves the prepared order and total') and an explicit do-not ('do not resend the document or addresses'), plus retry guidance on interrupted requests. It stops short of naming an alternative tool or stating when this should not be used instead of pay_order.

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

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

Annotations already declare a non-read-only, non-destructive, open-world mutation, and the description adds real value on top: what is returned (order ID, total, checkout URL, checkout session), that the draft never executes payment, and the required follow-up step for buyer approval. It does not cover permission/auth requirements, rate limits, or what happens on an unsupported form slug.

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 purpose and return values, then branched cleanly by payment protocol, with no filler sentences. There is minor redundancy, notably "Draft creation never pays" appearing here and again in the payment_protocol schema description.

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

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

The tool is complex (23 params, nested address and attachment objects), and while the output schema means returns need no explanation, the description still leaves out which forms are "supported", how the address parameters interact, and error behavior. It is adequate for the payment flow but thin for the address/document surface an agent must actually populate.

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 23 parameters and only 17% schema description coverage, the description carries most of the semantic burden and does not meet it. It only explains payment_protocol/buyer_email (which the schema already documents) and never clarifies the address-resolution trio (address_type/address_id/address_text/manual), fields, slug, or attachments, so most parameters remain opaque.

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?

"Prepare a supported workflow form for mailing" names a specific verb and resource, and the name itself pins down that this is the draft-creation path for workflow forms rather than letters, PDF uploads, or machine orders. The sibling distinction for x402 (create_machine_order) is explicit, though the description never contrasts itself with postalform.create_order_draft or create_letter_order_draft, leaving one ambiguity about which draft tool to pick.

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?

Clear routing is given for the payment paths: default hosted checkout, payment_protocol=mpp with buyer_email for the MPP challenge followed by postalform.pay_order, and postalform.create_machine_order for x402. What is missing is when to use this over the closely-named draft siblings, so the agent still has to infer the workflow-form-versus-other-order distinction.

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 real context beyond the annotations: 'Draft creation never pays', what the response contains, that typed or drawn signatures are accepted, and what an MPP call yields (PDF preview, fallback URL, challenge). Missing details are minor, such as draft lifetime or the role of request_id for idempotency.

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 purpose and return values, then branches through the payment paths in compact sentences. It is dense but nearly every sentence carries routing information; a mild cost is that the MPP and x402 branches interleave with the core description.

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 shape is well covered and there is an output schema, and the payment workflows are documented. However, for a 20-parameter tool with nested address objects, the required address-selection parameters and mailing options (mail_class, certified, double_sided) get no explanation anywhere, which leaves an agent guessing on mandatory inputs.

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 must carry the load. It explains payment_protocol, buyer_email, and the letter/signature shape, but leaves required fields like sender_address_type and recipient_address_type (Address vs Container vs Manual) and options like mail_class and certified entirely undocumented.

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

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

States a specific verb and resource ('Prepare letter text for mailing') plus the concrete artifacts returned (order ID, total, hosted checkout URL, checkout session). It explicitly distinguishes itself from PDF upload and from the x402 path served by postalform.create_machine_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?

Names the alternative routes and the conditions that select them: Stripe shared payment token via complete_checkout, otherwise the hosted checkout URL, MPP via payment_protocol=mpp followed by postalform.pay_order, and x402 via postalform.create_machine_order. When-not guidance is implied clearly (no PDF upload, no browser).

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 cover the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false), so the description must add process context. It does: buyer approval precedes payment, the unpaid response carries checkout_url and status_url, bulk MPP can complete via pay_order after a challenge, and campaign_url/recipient count/total should be reviewed before paying. It does not spell out what a failed or declined payment leaves behind, which keeps it below 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?

The content is front-loaded with purpose, then bulk mechanics, then payment routing, and almost every sentence carries a decision rule. It is dense but slightly overpacked, and it restates constraints (exactly one of recipients/csv_content) that also appear in the schema's bulk description.

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 29-parameter order-creation tool with an output schema, the description covers the decisions an agent actually needs: which content mode, how bulk differs from single, how payment handshakes and retries work, and what to do when no wallet is available. The remaining undescribed parameters are optional fulfillment options that the schema already enumerates.

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 38% across 29 parameters, so the description must carry meaning, and it does explain the mutually exclusive bulk.recipients vs bulk.csv_content choice, merge_fields template semantics, and omitting top-level recipient fields in bulk mode. However, many parameters remain unexplained in both places — color, double_sided, certified, certified_return_receipt, mail_class, postcard_size, mailpiece_type, signature_required, and the sender/recipient address_* family — so compensation is partial.

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 states a specific verb (Create ... and pay) with an enumerated resource set (single PDF, letter, workflow-form order, bulk letter campaign) and names the payment protocols. It also distinguishes itself from siblings by naming postalform.pay_order and the draft-then-complete_checkout path, so an agent can tell which tool to reach for.

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

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

The description gives explicit branch routing: bulk requires exactly one of bulk.csv_content or bulk.recipients plus a shared PDF or template; single-recipient Stripe-SPT clients should use a draft tool plus complete_checkout; clients without a compatible wallet should hand over checkout_url and poll status_url rather than recreating the order. It also states a negative rule (never recreate the order to change payment paths), which is exactly the kind of exclusion that prevents wrong calls.

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 real behavior beyond the annotations: 'Draft creation never pays', the draft-then-approve-then-complete sequence, and the fact that MPP mode returns a PDF preview, a hosted checkout_url fallback, and a challenge. Annotations only declare it is non-read-only, non-destructive, and open-world, so the no-charge guarantee and the handoff to complete_checkout/pay_order are the crucial additions. Pricing, expiration of the checkout session, and permission requirements are not covered.

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

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

Front-loaded with purpose and return values, with each subsequent sentence dedicated to one payment path. It is a dense single block covering three flows, so it stays serviceable but would read better split into short path-specific statements.

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 tool with nested PDF and address objects, an output schema, and 100% schema coverage, the description supplies what the structured fields cannot: the payment lifecycle and the sibling routing. Address-type selection and certified-mail variations are left entirely to schema descriptions, which is acceptable given their coverage.

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 the per-parameter meanings are already documented, and the description largely restates the payment_protocol=mpp plus buyer_email pairing that the schema itself declares. It does tie the two parameters into a workflow (MPP challenge for the same prepared order), which is a small addition over the schema but not enough to exceed baseline.

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

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

States a specific verb and resource ('Prepare an existing PDF for mailing' / create order draft) and enumerates what is returned (order ID, total, hosted checkout URL, checkout session). It also explicitly routes the x402 case to postalform.create_machine_order, so an agent can separate it from that sibling 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 concrete when-to-use branching: hosted checkout by default, complete_checkout if a Stripe shared payment token is available, payment_protocol=mpp plus postalform.pay_order for MPP, and create_machine_order for x402. It does not distinguish this tool from the other draft creators in the family (create_letter_order_draft, create_form_order_draft), which is the remaining ambiguity for document-type selection.

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 cover readOnly/idempotent/non-destructive, and the description adds substantial context on top: the 50-event cap on tracking history, null semantics for missing carrier evidence, the warning that a tracking number alone does not prove mailing or delivery, and the extra bulk-order fields (campaign_url, recipient count, per-status counts). This is exactly the kind of behavior-not-visible-in-schema disclosure that matters.

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?

Information is front-loaded with the return contents first, then interpretation rules, then exclusions, and nearly every clause earns its place. It is dense and packs many distinct claims into a few sentences, which borders on overload but remains scannable.

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?

A read-only, single-parameter tool with an output schema and full annotation coverage; the description nonetheless covers the interpretive traps (authorized vs paid, null carrier evidence) that an agent would otherwise get wrong. Nothing needed to invoke or interpret the result appears to be 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 100% for the single order_id parameter (documented as 'PostalForm order id.' with a UUID pattern), so the schema carries the parameter burden. The description never mentions order_id or adds format expectations beyond it, making the baseline 3 the correct score.

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

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

Names a specific verb ('Read') and enumerates exactly which parts of an order are returned: payment status and total, processing, stored mailing/carrier status, the latest 50 tracking events, and return receipt availability. It also explicitly contrasts with sibling mutations ('This read does not pay, mail, or acquire receipts'), so an agent can separate it from pay_order and the create_* 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?

Gives real decision guidance: authorized means awaiting capture even when is_paid=false, and 'Do not request another payment for authorized, processing or received payments' sets an explicit when-not for a follow-up action. It also redirects recipient-level lookups to the campaign dashboard. It stops short of an explicit 'call this before pay_order' statement, so selection is strong but not fully stated.

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

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

Annotations already declare 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?

Beyond the annotations (readOnly=false, destructive=false, openWorld=true) the description discloses the key behavioral fork: without payment_authorization it only returns a challenge; with it, it can pay and send real mail. It further notes no document or addresses are resubmitted and that the agent should follow the returned payment status, which is meaningful context for a charge-and-mail operation.

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

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

Six dense sentences, but they are front-loaded with purpose and the credential-switching rule, and each carries actionable content. The 'Review the preview or campaign_url, recipient count and total' line is the weakest for informational density but still supports verification before paying.

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 two-parameter, high-stakes payment tool with an output schema, the description covers the prerequisite (buyer approval), provenance of order_id, credential handling, side effects (real mail), retry semantics, and post-call behavior. Nothing an agent needs to invoke it safely 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 only 50%, and order_id has no schema description, so the description compensates by explaining where order_id comes from (draft tools with payment_protocol=mpp, or create_machine_order) and that it must be reused on retries. For payment_authorization it adds the consequence of supplying vs omitting it, though the challenge-vs-pay point partly duplicates the schema's own description.

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

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

The description opens with a specific verb and resource set: get an MPP challenge or pay an existing MPP PDF, letter, workflow-form order, or bulk letter campaign. It clearly scopes the tool against the draft-creation siblings by naming create_machine_order and the payment_protocol=mpp draft path.

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 when-to-use and how-to-sequence guidance: use the order_id returned by draft tools with payment_protocol=mpp or by create_machine_order, and when switching from create_machine_order omit the credential first to obtain this endpoint's challenge. It also states the retry rule (reuse the same order_id) and the prerequisite of buyer approval.

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=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely new behavior: that addresses are validated and that the result is a widget containing a create-draft action, which tells the agent what the output is and what the next step should be. It stops short of mentioning cost, expiry, or what happens on validation failure.

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

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

A single tight sentence pair, front-loaded with the 'use this to' cue and no filler. It is well sized, though the dense enumeration of three actions in one sentence slightly compresses detail that could have been spent on parameters.

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

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

For a 17-parameter tool with nested address objects and zero schema descriptions, the description leaves the agent without guidance on how to supply addresses or which options exist. The output schema means return values need not be explained, but the input side is materially under-covered.

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

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

Schema description coverage is 0% across 17 parameters with nested objects and three enums (sender/recipient_address_type, mail_class). The description says nothing about address types, manual vs. ID vs. text address forms, letter body limits, render options, or the request_id idempotency key, so it fails to compensate for the coverage gap beyond a vague nod to 'letter' and 'addresses'.

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

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

The description names a specific verb and resource ('preview ... a mailed letter') and enumerates the three things it does: renders the letter, validates addresses, and returns a widget. It implies separation from the create-draft siblings via 'non-writing preview' and 'before creating checkout', but never names postalform.create_letter_order_draft explicitly, so sibling differentiation is only partial.

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?

'before creating checkout' gives a timing/ordering cue for when the tool fits, which is real but implicit guidance. There is no explicit when-not clause and no named alternative among the many create_* siblings, so the agent must infer the routing itself.

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

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

Annotations already declare 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.