PaperAgent — Send Physical Mail

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

Goes well past the annotations: the 24-hour freeze, zero cost, no print/postage until send_letter, the 7+ page hard refusal (refused, not trimmed), and refusal-not-substitution for unsupported tiers and colour. These are exactly the side-effect and failure-mode facts an agent needs for a non-destructive-but-stateful create.

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, outputs, then constraints and next step, and nearly every sentence carries operational weight. The non-electronic point is made twice ("nothing reaches the recipient electronically" plus "the only way this letter arrives is on paper"), which is mild redundancy in an otherwise dense 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 6-parameter nested-object tool with an output schema, it covers required inputs, sizing limits, pricing rules, unsupported fields, address scope, and the follow-up call. An output schema exists, so return-value details are correctly left to it.

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 real meaning the schema lacks: page-count pricing behaviour, the one-sided vs duplex threshold, the ~2,400 word guidance, and the fact that body_file is currently rejected. Tier and colour semantics largely duplicate schema text, capping it below 5.

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

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

Names a specific verb and resource (create a physical letter draft) and states its output artifacts (draft_id, page count, total price). It also explicitly distinguishes itself from send_letter and preview_draft, so an agent can route correctly 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 sequencing rules: call get_pricing before choosing a tier, call preview_draft next, split over-long documents into two letters, US domestic addresses only. It also states when-not (not email/fax/text) and which fields to omit (colour, from_address_id).

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, and the description clears it by disclosing a non-obvious domain behavior: USPS does not scan First-Class letters at delivery, so a Standard letter terminates at an expected date and never reports arrival. 'This creates nothing and mails nothing' is somewhat redundant with readOnlyHint but usefully reinforces it.

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 what is returned, then the delivery-confirmation caveat, then the safety clarification. Every sentence carries distinct information; nothing is padding.

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

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

An output schema exists, so return values need not be restated, and annotations cover the safety profile. For a single-parameter read tool, the description supplies everything an agent needs to call it correctly and to report its result honestly.

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

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

Schema description coverage is 0% for the single letter_id parameter, so the description carries the burden and adds no format, source, or validity guidance for it. It only establishes that the identifier refers to a single letter; the param name is self-explanatory enough that this is marginally adequate rather than a failure.

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 and resource with scope: 'Return the current state of one letter', plus the exact data points returned (location, USPS date, estimated delivery). The phrase 'one letter' implicitly separates it from list_letters, but no sibling is named explicitly, so it stops short of a 5.

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 interpretation rule ('do not tell the user a letter arrived unless the status itself says so') and scoping ('one letter'), which implies when to reach for it. However, it never states when to prefer this over list_letters or how to obtain a letter_id, so usage is only implied.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior, but the description adds critical pricing semantics: amounts are in US cents, there is no volume discount, no per-page charge, no colour printing, and New York sales tax is always added regardless of destination. It also reinforces safety with 'This creates nothing and mails nothing.'

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

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

The description is front-loaded with the core purpose, then packs pricing rules and quoting guidance into compact sentences with no wasted text. 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?

Given the zero-parameter schema, rich annotations, and an output schema that covers return structure, the description is complete. It closes the key remaining gaps: pricing rules, tax behavior, and the instruction to call before quoting costs.

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 per the rubric the baseline is 4. The description adds no parameter-specific details because none exist, which 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?

The description states a specific verb and resource: return the published USPS letter price list. It details exactly what the list contains (products, costs, page coverage, sales tax applicability), so an agent can distinguish it from all sibling tools immediately.

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

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

It explicitly says to call this tool before telling a user what a letter will cost, and then instructs how to quote the result (tier total plus New York sales tax). No sibling tool offers pricing, so no alternative routing is needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description still adds useful domain context: result ordering, the fields present on each item, and an explicit guarantee that nothing is mailed — a meaningful assurance given siblings like send_letter exist. It does not describe pagination behavior beyond what the cursor parameter implies.

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

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

Three short sentences, front-loaded with what is returned before the usage hint and the safety disclaimer. No filler and nothing repeated.

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

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

An output schema exists, so return structure need not be spelled out, and the annotations fully cover the safety profile. Purpose, usage context, ordering and the no-side-effect guarantee are all present for a simple two-parameter list 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%: 'limit' documents its default of 20 and 'starting_after' explains it takes the next_cursor from the previous call. The description adds no further parameter meaning, which is the expected baseline when the schema does the heavy lifting.

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 ('Return this account's letters') plus the ordering ('newest first') and the per-item fields returned ('status, mail date and total'). The line 'Use this to answer questions about what has already been sent' and the negative framing 'creates nothing, changes nothing and mails nothing' separate it from the mutating siblings like create_draft and send_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?

'Use this to answer questions about what has already been sent' gives a clear use context, and the closing sentence implicitly excludes the create/send paths. It stops short of naming the closest alternative (get_letter_status for a single letter) or stating when-not to use it.

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 behavior beyond the annotations: it discloses a side effect ('Refreshes the stored price quote when pricing has changed') and explicitly negates the dangerous actions ('does not create an order or mail a letter'). This explains why readOnlyHint is false, which the annotations alone cannot convey.

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

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

Four sentences, front-loaded with the return contract, then the pricing side effect, then usage, then the negative scope. Each sentence earns its place, though the return-value sentence is somewhat dense.

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 re-explained, yet the description usefully links the returned total to send_letter's confirm_total_cents. For a single-parameter preview tool, nothing needed 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?

With one required parameter and 0% schema description coverage, the description carries the burden but never describes draft_id's format or where it comes from. The context makes the meaning inferable, but there is no added parameter-level detail.

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 ('Return a link to the rendered PDF of a draft') plus the two satellite outputs (page count, total price). It also distinguishes itself from send_letter, so an agent can tell the preview step apart from the send step without opening the schema.

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

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

Explicitly says to use it 'before calling send_letter' to show the user what will be printed and what it costs, giving clear sequencing. It does not discuss alternatives such as get_pricing or when a preview could be skipped, so it stops just short of full when/when-not 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 destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=true, and the description reinforces rather than contradicts them while adding context the annotations cannot convey: the call only returns a payment link, no paper is printed or postage bought until payment completes, and the operation becomes irreversible at print time. It also discloses a failure mode (quote mismatch aborts the send) and the domestic-address restriction.

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

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

The description is dense but front-loaded: action and artifact first, then the payment-link caveat, then usage triggers, then the email exclusion and address scope, then prerequisites and the irreversibility warning. Every sentence contributes a distinct fact and no sentence is filler.

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

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

For a destructive, open-world mutation with an output schema (which removes any need to describe return payloads), the description covers prerequisites, cost-confirmation flow, domestic scope, irreversibility, and the not-an-email distinction. Nothing an agent needs in order to decide and call 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 description coverage is 100%, so all three parameters are already fully documented in the schema, including the idempotency-key reuse behavior and the confirm_total_cents match requirement. The description largely restates these ('confirm_total_cents matching the current quote', 'requires a draft_id from create_draft') and adds only the linkage to create_draft as genuinely new meaning. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

States a specific verb and resource ('Create an order for a real, physical letter through the United States Postal Service') and immediately scopes it against the obvious confusable sibling by declaring 'This is NOT email — use an email tool for email.' An agent can distinguish this from create_draft, preview_draft, or an email tool 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?

Gives an explicit trigger ('whenever the user asks to mail, post, send by post, or physically send a letter'), an exclusion ('This is NOT email'), a geographic limit ('US domestic addresses only'), and hard prerequisites (a draft_id from create_draft, a confirm_total_cents matching the live quote). This is exactly the when/when-not/alternatives coverage the dimension asks for.

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 (which only assert destructiveHint=false and readOnlyHint=false), the description discloses the re-pricing consequence ('previous total is void'), the 6-page constraint and its enforcement ('a replacement that renders to 7 or more pages is refused and the draft is left as it was'), and that partial failure leaves state intact. That is exactly the kind of behavioral detail annotations cannot carry.

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 action and followed by consequence, constraint, and scope boundary. Nothing is redundant and each 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?

With an output schema present the return values need no explanation, yet the description still flags the new page count and quote. Combined with annotations and complete nested schema coverage, an agent has everything needed to call this correctly.

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

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

Schema coverage is high (83%), so the baseline is 3, but the description goes past the schema by tying the body param to the 6-printed-page refusal rule and its state-preservation behavior, and by reinforcing that the new quote must be surfaced to the user before sending.

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 ('Change the recipient, body, tier or colour of a draft') and scopes it to one 'that has not been sent'. It also names the editable fields, so an agent can distinguish it from create_draft, send_letter and preview_draft 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?

It gives clear context — a draft that has not been sent — and closes the 'creates/mails' door ('This creates nothing and mails nothing'), which implicitly routes send_letter and create_draft to their own tools. It does not, however, explicitly name those alternatives or state when-not to use it in those words.

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 open-world, so the safety profile is covered. The description adds real context beyond them: the address is sent to the Google Address Validation service and nothing else (a privacy disclosure), and 'this creates nothing and mails nothing' reassures about side effects. It stops short of saying what an invalid/unverifiable address yields beyond 'warnings' or whether the call can fail.

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 sentences, front-loaded with purpose, then usage, then scope limits. Each sentence carries information, though 'This creates nothing and mails nothing' partially overlaps with the destructiveHint=false annotation.

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

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

With an output schema present, return values need not be explained, and the safety profile is covered by annotations. The description supplies the remaining essentials: correct usage ordering, the external dependency, and the US-only/complete-address boundary conditions.

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% and every nested field (name, line1, line2, state, postal_code) is documented in the schema, so the baseline is 3. The description's 'requires a complete street address' and 'does not look up... from a name' mostly restate the required list plus behavior, adding little syntax or format detail beyond the schema itself.

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 ('Check a US postal address') and describes the outcome ('return it in the normalized form the envelope will be printed with, plus any warnings'), which distinguishes it from every sibling. An agent can tell this apart from create_draft or get_letter_status 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?

Explicit routing: 'Use this before create_draft whenever the address came from a person rather than from an earlier tool result' names both the alternative and the selecting condition. It also names when-not-to-use by exclusion: no lookup from a name, no non-US addresses.

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