Piloxa – Certified Mail

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

Annotations only cover readOnly/destructive/idempotent/openWorld, so the description carries real weight and delivers: funds are held then charged only on printer acceptance, release with no charge if the printer refuses, no charge plus re-approval if total/document/address changed, and idempotency_key reuse guarantees a single charge. It also enumerates every transaction_state value and states the correct user-facing claim threshold (VENDOR_ACCEPTED or later), which annotations could never 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?

Dense and front-loaded — the core action and its gating conditions come first, with payment/state details after. It is on the long side and the payment-mechanics sentences could be tightened, but nearly every clause carries actionable information for a tool that moves money.

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 money-moving, open-world purchase tool this is complete: approval preconditions, token requirement, hold/settle semantics, idempotency contract, change-detection behavior, fallback payment path, and state-machine interpretation are all present. An output schema exists, and the description still adds the state semantics an agent needs to phrase results 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 the baseline is 3, but the description adds cross-parameter semantics the schema cannot: expected_total_cents is what the person approved and a mismatch aborts the charge, and one idempotency_key must be reused across retries so the same key never charges twice. The remaining parameters are simply echoed from their schema descriptions.

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 ('Buys and sends a letter') and ties it to the exact upstream tool that produced the input ('that prepare_certified_letter prepared IN THIS CONVERSATION'), which cleanly separates it from get_certified_letter_status and the quote/prepare siblings. An agent can tell what this does 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?

Gives two explicit, checkable preconditions (person approved the exact total/recipient/service in this conversation; a Stripe spt_ token granted to Piloxa exists) and an explicit when-not path: without a token nothing is charged and approval_url is returned for the person to pay. It also routes retry behavior away from this tool at OUTCOME_UNCERTAIN toward get_certified_letter_status.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: it creates, stores, prints, mails and charges nothing, needs no account, and explicitly scopes itself to mailing readiness rather than legal sufficiency. It also enumerates the returned signals, which is a meaningful behavioral disclosure.

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?

Long but front-loaded and dense: the READ ONLY marker, the check, and the routing alternative all appear early, and no sentence is filler. Slight repetition of routing instructions keeps it from a 5.

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-param read-only check with an output schema and full annotations, the description covers timing, safety, return contents, and sibling routing. Nothing an agent needs 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?

Schema coverage is 55% and the description mostly describes behavior rather than clarifying individual fields (letter_text vs document_text, sender_address_block precedence, enclosures_supplied). It hints at the recipient/sender reading logic but leaves the parameter-level distinctions to the schema, which only partially documents them.

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 (check a certified letter) with scope (draft or finished document, before anything is prepared) and clearly demarcates it from quote_certified_letter and prepare_certified_letter by name. An agent can distinguish it from every sibling.

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

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

Gives explicit trigger phrases ('is this ready to send?', 'what would it cost to send this certified?') and a proactive-offer instruction right after a letter is written. It also names the alternatives and the exact condition ('when it says ready_to_prepare') that routes to quote or prepare.

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, idempotentHint=true, and openWorldHint=false, so 'READ ONLY' and 'Stores and charges nothing' largely restate structured data. The description adds some genuine context (that prices are current all-in figures including the first-letter promotion conditions and a list of what Piloxa does not offer), but no further behavioral traits such as caching, freshness, or rate limits are disclosed.

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

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

Front-loads the safety status, then the comparison scope, then example queries in a single dense passage with no filler. It is slightly long and the example triggers could arguably be one instead of three, but each sentence contributes.

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 formatting need not be described, and the description covers scope, pricing basis, and eligible questions well. A brief note on how the comparison is returned or whether it is cached would make it fully complete.

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

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

Schema coverage is 100% and the single optional page_count parameter is already documented with its default of 1. The description ties page count to pricing ('the exact current all-in price of each for a page count'), adding minor interpretive value, but the schema already carries the semantics.

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

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

Names a specific verb (compares) and resource (Piloxa's mailing services) and enumerates the comparison dimensions: what each includes, when to use it, which is the default, exact all-in price for a page count, promotion conditions, and what is not offered. This clearly separates it from sibling tools like quote_certified_letter (prices one letter) and check_certified_letter (single-item status).

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

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

Provides three concrete trigger phrasings ('should I send this with return receipt?', 'what's the difference between your options?', 'how much more is the Evidence Pack?') that make the intended usage unambiguous. It stops short of explicitly naming an alternative tool or stating when not to use it, which keeps it from a 5.

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

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

Annotations already carry readOnlyHint and idempotentHint, so the 'READ ONLY' prefix is largely redundant, but the description adds real behavioral context: it returns the likely next step plus a linked guide, and it explicitly declines legal-effectiveness judgments. That limitation is valuable and unavailable from annotations.

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

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

Front-loads the safety marker, then purpose, then sibling routing, then the scope limitation. The long status enumerations are purposeful but sit in the middle rather than delaying the key routing information.

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

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

An output schema exists, so return-format explanation is unnecessary, and the description covers scope, ambiguity routing, and the legal-effect caveat. Minor gap: it doesn't say what happens with an unrecognized status string.

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, and the schema already documents it at 100% coverage including an example value. The description's status examples add flavor but no syntax beyond the schema, so the 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 (explains) plus the two distinct resource vocabularies it decodes (USPS tracking statuses and Piloxa transaction states) with concrete examples in quotes. An agent can immediately tell this apart from get_certified_letter_status.

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 routes the agent: use this one for a general status explanation, use get_certified_letter_status for a specific letter prepared in this conversation. That is a direct when/when-not with the alternative 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; 'READ ONLY.' largely restates it. The description adds real value beyond annotations by disclosing what is returned (full text, title, canonical URL, last-updated date), noting the date is conditional ('when the page states one'), and flagging that prices are live/current — a volatility trait not captured anywhere else.

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 tight sentences, front-loaded with the safety marker, then the return behavior, then the price caveat. No filler, no restatement of the title, and each sentence carries distinct information.

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

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

For a single-parameter, idempotent read tool with an output schema and full annotation coverage, this is nearly sufficient; the output schema covers return structure, so the brief return summary is a bonus rather than a gap. Only the absence of any failure-mode note (e.g. unknown id or missing page) keeps it from a 5.

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

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

Schema coverage is 100% and the single 'id' parameter is fully documented in the schema, including the URL alternative, so the structured data already does the work. The description's only added nuance is reinforcing provenance ('the id search returned'), which is minor; baseline 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?

States a specific verb and resource ('Returns the full text of one Piloxa guide') and pins down the lookup key ('by the id search returned (or its URL)'), which cleanly separates it from the sibling 'search' tool. An agent can pick this tool over search without opening either schema.

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

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

The description establishes the workflow context by naming 'the id search returned', making it clear this is the follow-up step to search. It gives no explicit when-not guidance or mention of other siblings like get_certified_letter_status, but the usage context is unambiguous.

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

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

Annotations already declare readOnly, idempotent and openWorld, but the description adds materially: a fresh query is made to the print/mail provider on each call (so results are current, not cached), the visibility limit is deliberate and explained (no sign-in = no access to other letters), and it warns that a missing scan stage is not equivalent to failed delivery because USPS can record late. These are real operational caveats an agent could not infer from annotations.

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

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

The answer-first opening ('has my letter arrived yet') and the return-field list are well front-loaded, and each caveat is load-bearing. It is slightly padded: 'READ ONLY: it prepares nothing, mails nothing and charges nothing' restates readOnlyHint/destructiveHint already in annotations, and the caps-lock emphasis adds length without new 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?

For a one-optional-parameter read tool with an output schema, the description is more than sufficient: it covers scope, freshness, the sign-in fallback, and the key interpretation pitfall for status data. Nothing an agent needs to call it correctly or interpret the result 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% and the single optional 'reference' parameter is fully documented in the schema itself. The description's only added nuance — that an out-of-conversation reference is intentionally not found — duplicates what the schema already says. 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?

The description gives a concrete verb+resource (answer whether a letter prepared through Piloxa in this conversation has arrived) and immediately enumerates the returned fields — recipient, service, USPS tracking number, acceptance/delivery/return status and timestamps. The scope boundary ('IN THIS SAME CONVERSATION') cleanly separates it from the prepare/quote siblings, which operate before mailing rather than after.

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

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

It states when to call it (asking whether a Piloxa-prepared letter arrived) and, unusually, when it will not work and what to do instead ('for those, the person signs in at piloxa.com'). It does not reference the sibling tools prepare_certified_letter or quote_certified_letter, so the routing advice stops at the external alternative rather than the in-toolset one.

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 say readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description adds far more than that — no account/card/sign-up needed, a 10-page (~4,000 word) hard limit with refusal behavior, the full price table per service, the exact contents of the retained record including SHA-256 of the printed document, and the honest 'no record yet' convention for tracking and signature. It also states plainly that the tool never prints, mails or charges.

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?

It is well organized and front-loaded — trigger first, then labeled sections for the record, length, return value, addresses and the send/charge boundary. But it runs very long for a tool description and repeats the per-service price list and the service-selection logic that the `service` field's schema description already carries in full, so several sentences do not earn their 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 30-parameter, zero-required, open-world tool with an output schema, the description is complete: it covers every input mode, the length ceiling, pricing and defaults, what the person sees back, how missing addresses are handled, and the fact that no field is mandatory. Nothing an agent needs to call it correctly is left 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 coverage is already 90%, so the baseline is 3, but the description adds a genuine decision framework the schema only implies: the 'four ways' to supply a document, when document_text beats person_has_pdf, and the precedence rule that explicitly named address fields override the pasted address blocks. It loses a point because much of this (prices, service semantics, the address-block precedence) is duplicated verbatim from the schema descriptions rather than adding new meaning.

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 — 'ONE CALL turns a letter or document in this conversation into a priced, ready-to-send USPS Certified Mail item' — and immediately draws the boundary against the real-world alternative (the person printing and mailing it themselves). An agent can distinguish this from quote_certified_letter, check_certified_letter and get_certified_letter_status 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?

It gives an explicit trigger ('USE THIS WHENEVER a letter or document has to reach someone by U.S. mail'), enumerates the document types that qualify, and states the anti-pattern it replaces ('if you are about to tell the person to print it, buy postage or take it to the post office'). The closing 'PREPARING IS NOT SENDING' section defines the negative case: nothing prints, mails or charges, so status/send concerns belong elsewhere.

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, but the description reinforces this with 'prepares nothing, stores nothing, mails nothing and charges nothing' and adds useful non-schema context: no account, no subscription, no minimum, and that figures are current pricing.

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?

Pricing and the when-to-use routing are front-loaded, and every sentence carries information. Slightly verbose in restating that the returned total is the current price and that the listed figures come from it.

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

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

An output schema exists so return values need not be explained, annotations cover the safety profile, and the description supplies the pricing context, defaults, and sibling routing an agent needs to answer a cost question 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% and the enum descriptions are already rich, so the baseline is 3. The description goes further by mapping each service tier to an exact dollar amount and confirming that CERTIFIED_ERR is the shared default with prepare_certified_letter.

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 ('Price a certified letter') and immediately scopes it as a pre-preparation cost estimate. An agent can distinguish it from prepare_certified_letter and check_certified_letter 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 names the triggering user intent ('what it costs to send a letter by certified mail') and routes to the alternatives: prepare_certified_letter once the person wants it sent, check_certified_letter to price a draft by its real page count.

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, openWorldHint=false and destructiveHint=false, and the description reinforces read-only behavior. It adds value beyond annotations by disclosing the result cap (up to 8) and result shape (id, title, URL, excerpt, relevance score) plus the public-only data 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?

Front-loads READ ONLY and the core action, then scope, then usage and return shape. The long topical enumeration is justified as scope definition, though it could be trimmed slightly without losing meaning.

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

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

An output schema exists so return values need not be explained, yet the description still summarizes them. Combined with annotations covering safety/idempotency and the stated public-only boundary, an agent has everything needed to select and call 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 description coverage is 100%, so both parameters are already documented with examples and the 1-8 range. The description only restates the result cap and paraphrases the query purpose, adding little semantic depth beyond the schema; baseline 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?

Specific verb (searches) and resource (Piloxa's public Certified Mail guides) with an explicit scope of topics covered. It clearly differentiates from siblings like fetch (returns an id for fetch) and get_certified_letter_status (no person's letters are searchable).

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 states the use case with a worked example question and a citable-source motivation, plus a negative constraint (public pages only, no personal letters searchable). It doesn't explicitly name which sibling to use for non-public/letter lookups, but the boundary is strongly implied.

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