Sendpaper

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds a genuine precondition not present in structured data (unpaid-only eligibility) plus an escalation path for paid orders, though it never states what happens if the rule is violated or whether the cancellation is reversible.

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

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

Two short sentences, zero filler, with the core eligibility constraint front-loaded ahead of the fallback path. Every sentence earns its place.

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

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

For a single-parameter, no-output-schema tool whose annotations already carry the safety profile, the definition covers purpose and eligibility adequately. It is only slightly thin on failure behavior and on how the agent should confirm an order is unpaid before calling.

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?

There is one parameter (order_id) with 0% schema description coverage, so the schema provides no semantics. The description refers only to 'an order' and adds nothing about the identifier's format or source, leaving the parameter essentially undocumented.

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

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

The description states a specific verb and resource ('Cancel an order') and narrows the scope to unpaid orders, which implicitly distinguishes it from pay_order and get_order. It is clear but never names a sibling tool to route the agent, so it stops short of full differentiation.

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

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

It gives an explicit when-to-use condition (order not yet paid) and a when-not path with an alternative ('email support before they are printed'). It does not, however, tell the agent to verify payment status via get_order first, so the workflow around the tool is incomplete.

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

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

Annotations only declare the mutation/open-world/safe-to-modify profile; the description adds substantially more: the order is created but mails only after payment, a payment link is returned, and pricing differs by service tier. That work-flow disclosure (create → pay → mail) is the important behavioral context an agent needs. It omits auth requirements and any rate/latency notes, so not 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 core action and its side effect are front-loaded in the first sentence, and the page/envelope limits come with it. The certified pricing sentences are dense but partly duplicate the enum description in the schema, slightly bloating an otherwise efficient definition.

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 6-parameter, nested-object mutation with no output schema, the description covers the essential lifecycle (order → payment link → mail), the physical constraints, and the tier tradeoffs. Minor gaps remain around the return payload beyond 'payment link' and the idempotency parameter, but 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?

Schema coverage is 50% and the schema already documents certified, the address fields, and customer_email well; the description's restatement of certified prices adds little beyond the enum description. Critically, idempotency_key has no description anywhere and the to/from/content nesting is undocumented in prose. The description partially compensates but leaves real gaps, so baseline 3 is right.

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 ('Create a printed letter order') plus concrete physical scope (up to 3 pages, 8.5x11, #10 envelope) and the side effect of producing a payment link. The 'letter' vs 'postcard' distinction from the create_postcard sibling is immediately obvious, and the payment-link/mails-after-payment framing separates it from 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?

It gives explicit when-to-use guidance for the certified tiers ('use these when the user needs proof (landlord notices, legal or tax replies, disputes)') and clarifies the two-step flow ('Mails only after the user pays'). It does not explicitly route between siblings like create_postcard, but the usage context for the key decision (certified vs regular) 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?

Annotations only declare the generic profile (not read-only, not destructive, open-world). The description adds genuinely useful behavior: the tool returns a payment link and does not actually mail until the user pays, which is critical for an agent managing order state. It stops short of covering failure modes or idempotent-retry behavior.

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

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

Three short sentences, front-loaded with the core action and the payment outcome. Each sentence carries information; no redundant restatement of the title.

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

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

For a nested, mutating tool with no output schema and low schema coverage, the description covers the main flow but omits what the agent most needs to operate safely: the purpose of idempotency_key for retries, and what happens to state if the user never pays. The listed front/back semantics partially fill the schema gaps.

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

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

Schema description coverage is only 33%, so the description must compensate. It does clarify the front/back split and the image-URL-vs-headline choice for the front, but leaves idempotency_key completely unexplained and says nothing about customer_email's role beyond what the schema already documents.

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 ('Create a postcard order'), names the two supported sizes, and describes the resulting artifact (a payment link). It does not explicitly contrast itself with the sibling create_letter, so an agent must infer the postcard-vs-letter distinction from the tool name alone.

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

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

It implies the correct entry point for the postcard flow and warns that mailing only happens after payment, which hints at the follow-up pay_order step. However, it never states when to choose this over create_letter or what prerequisites exist, leaving usage largely 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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only the id format hint ('ord_...') and nothing about return format, error cases, or rate limits; with annotations carrying the load, this is adequate but thin.

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 zero filler; the identifying detail (id prefix) is placed where it is needed.

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

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

For a one-parameter read tool whose annotations already cover safety, this is nearly complete. The one remaining gap is that with no output schema, the description does not hint at what 'status' values are returned, which an agent might want.

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% and the single parameter is only typed as a string, so the description must compensate. It does so usefully by naming the parameter's role (order id) and its expected prefix ('ord_...'), which is more than the schema offers.

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 ('Get the status') and resource ('postcard or letter order'), and narrows the scope to a single order by id. It is clearly distinct in kind from create_*, cancel_order, and pay_order, though it never names a sibling or draws the boundary 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?

The description gives no when-to-use or when-not-to-use guidance and never references the alternatives in the sibling set (cancel_order, pay_order, get_pricing). Usage is only inferable from the tool's name and verb.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: prices are in USD, include printing plus USPS First-Class postage, and apply to US addresses only. It does not describe the return shape or whether results are paginated or cached.

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 sentence with zero filler, front-loading the verb and resource and packing the pricing-scope caveats into a parenthetical. Every clause carries 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 no-parameter, read-only lookup, the description covers what is being priced and the geographic/currency constraints, which is the main ambiguity. Since there is no output schema, it could have sketched the returned fields, but nothing required to call 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?

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. Schema description coverage is 100% and consistent with the empty property set.

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

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

States a specific verb ("List") and resource ("mail products and prices"), which is clearly distinct from the order/creation siblings. It does not explicitly name or differentiate from a sibling tool, but the resource scope makes the distinction obvious without opening any schema.

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

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

Usage is only implied: an agent can infer this is the price-lookup step before create_letter/create_postcard/pay_order, but the description never says when to call it or when not to. No 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?

Annotations already declare the mutation profile (readOnly=false, destructive=true, idempotent=true, openWorld=true). The description adds real context beyond that: success transitions the order to print, and the token must be user-approved and scoped to at least the order amount. It does not describe failure/rejection handling, but the safety-critical behavior is covered.

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

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

Two sentences, front-loaded with the core action and followed by the required precondition. No filler; every clause carries actionable 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?

There is no output schema, and the description does summarize the success outcome (order paid, goes to print). Preconditions for the token are stated. Only failure behavior and any idempotency implications for repeat calls are 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 only 50%: shared_payment_token is documented in-schema while order_id is not. The description does add meaning to the token (spt_… format, user-approved, scoped to at least the order amount in USD), which helps compensate, but order_id semantics are left untouched.

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 (order), plus the precondition that the order is unpaid. It is instantly distinguishable from siblings like cancel_order, get_order, and create_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?

Gives a clear gating condition: 'Use only after the user approved the purchase.' This tells the agent when the tool is valid. It does not, however, name alternative siblings or describe what to do for an already-paid order, 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.