Print and Mail Company

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

Goes well beyond the annotations by disclosing the refund-to-credit side effect, the irreversibility boundary for printed/posted letters, the account requirement, and a confirmation expectation. These are exactly the behavioral facts an agent needs for a destructiveHint=true 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?

Front-loads the trigger condition and stays focused, with each sentence carrying a distinct instruction. There is minor overlap between 'drafts and paid letters not yet in production' and the schema's restatement of the same rule, but no real waste.

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 mutation with no output schema, the description supplies the missing pieces: refund outcome, irreversibility limits, account requirement, and disambiguation from siblings. Nothing an agent needs to call it correctly is absent.

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 letter_id parameter is fully documented in the schema, including its source tools and example format. The description restates the cancellable-state constraint but adds no syntax or format detail beyond what the schema already provides, so the 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+resource (cancel a letter created via this service) and immediately scopes it to drafts and paid-but-unproduced letters. It also distinguishes itself from sibling compose_letter by clarifying that this cancels our letter, not a third-party contract.

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 covers when to use it, when not to (letters already printed or posted cannot be recalled), the alternative tool for a different need (compose_letter for contract cancellation letters), and a prerequisite action (ask the user before cancelling).

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 mark this read-only, idempotent and non-destructive, and the description still adds substantial context: the file is not stored, nothing is sent, and it works without sign-in. It also names the output fields (compliant, all_pages_a4, us_letter_note, pages[].scale_percent) that drive the decision, which is exactly what a no-output-schema tool needs.

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 trigger and the verification behavior before the printing-rule detail, which is good ordering. However the middle section reads as dense run-on sentences about print paper selection that partly belong to the printing workflow rather than to a margin check.

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 no output schema, the description carries the burden and does so: it explains the verification result, the all_pages_a4 pitfall (false for a printable US Letter PDF), and how to interpret scale_percent when pages are mixed. Auth, storage, and input-method concerns are all addressed.

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 (pdf_url, pdf_base64) are already fully documented including the alternative and the size caveat. The description only restates 'accepts a public https URL or base64', adding no new syntax or constraint beyond the schema, 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?

States a concrete verb and resource: it verifies page size (A4/US Letter) and required free margins on every side, and lists pages needing changes. It also distinguishes itself from the sibling that remediates problems (fix_document_margins), so an agent can tell the two apart without reading 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?

Gives a clear trigger ('when the user has a PDF they want printed and posted and it should be checked first') and names the follow-up path via upload_document plus fix_document_margins. There is no explicit when-not-to-use case, so it stops just short of the top band.

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, it discloses that nothing is sent or charged, that a draft is created with an exact price, the SENDER_DETAILS_REQUIRED failure mode, and how sender details are saved or preserved on the account. It also covers body markup, print-check behavior, and that the sender can be in any country.

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 front-loaded with the when-to-use and the draft-then-send workflow before the caveats. It is dense but justified for a 14-parameter tool, though the real-name requirement and body-formatting details are partially repeated in the schema, costing some conciseness.

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 complex nested 14-parameter mutation with no output schema, the description covers the workflow, pricing, confirmation requirement, error modes, sender-details persistence, and formatting rules. An agent has enough to invoke it correctly without guessing.

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 genuine meaning beyond the schema: the body formatting rules, the sender-block-as-account-details semantics, and which fields cause SENDER_DETAILS_REQUIRED. It does repeat some schema details rather than only 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 gives a specific verb and resource (compose a new paper letter from text, render an A4 DIN 5008 letter, create a draft) and lists concrete use cases like cancellations and formal notices. It clearly separates composing from sending by naming send_letter, but never addresses the sibling create_letter, which an agent could easily confuse with this 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?

It states when to use the tool with concrete scenarios, spells out the required follow-up workflow (show draft and total, ask for confirmation, call send_letter), and explains the first-letter sender-details prerequisite. The missing piece is guidance on how this differs from the create_letter sibling.

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 non-read-only, non-destructive, non-idempotent, closed-world, so the bar is lower, yet the description adds real behavior: draft-only, no charge or dispatch, the exact total quoted in user currency, and named failure modes (SENDER_DETAILS_REQUIRED, paper_choice_required, INVALID_ADDRESS, refused too-small envelope). It also explains the saved-versus-kept sender state ('on_file'/'kept'). It stops short of describing what the draft object itself returns, but with no output schema that is a minor gap rather than a serious one.

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?

Well front-loaded: the trigger condition comes first, then the draft/no-charge contract, then prerequisites and the paper-size wrinkle. It is dense rather than padded, though it is long enough that the sender-details paragraph partly duplicates schema text and could be trimmed.

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

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

For a 9-parameter nested-object creation tool with no output schema, the description covers the pieces that actually cause failed calls: first-letter sender details, region-required countries, the US Letter to non-US paper choice, envelope sizing, and the confirmation handoff to send_letter. An agent can call this correctly without further discovery.

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 nested sender/recipient blocks already document region rules, ISO codes and paper_size conditions, so the description mostly restates what structured data provides. It does add one genuinely non-schema insight — that every envelope carries the company return address, so the user's own address belongs in the document — which nudges it to the top of the baseline band.

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?

Opens with a concrete precondition (uploaded PDF plus recipient address) and a specific verb (creates a draft for posting by ordinary or registered mail), and explicitly distinguishes the act from send_letter. It also pins down the ambiguous term 'certified' versus Einschreiben/lettre recommandée, so an agent knows exactly what this tool produces.

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?

States when to use it, names the upstream alternatives (document_id from upload_document/compose_letter, or upload_id from create_upload_link), and gives an explicit when-not: nothing is sent or charged, and send_letter is the follow-up call after the user confirms. The user-facing prerequisites (sender details, paper choice) are attached to the right moments.

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description discloses the key non-obvious traits: the link is handed to the user who pays externally, the assistant cannot pay, and calling the tool charges nothing. It also states the auth requirement ('Needs the user's account'), which the annotations do not cover.

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 trigger condition, then the return behavior, then the safety/auth caveat. Every sentence earns its place and nothing is redundant.

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 no output schema, the description steps in and describes the return value (a link to the payment page), plus the auth requirement and the no-charge guarantee. An agent has everything needed to call it and explain the result to the user.

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 letter_id description already explains the two modes (pay a draft vs. omit for credit), so the schema carries the parameter burden. The description's phrasing 'add credit, or to pay one specific draft letter' mirrors that without adding new syntax or constraints, which is the expected baseline 3.

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

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

The description states a specific verb and resource ('Returns a link to the payment page') and scopes it precisely to two cases: adding prepaid credit or paying one draft letter by card. No sibling (create_upload_link, get_balance, send_letter) shares this resource, so an agent can identify it 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?

It gives an explicit trigger: 'Use this when the user needs to add credit, or to pay one specific draft letter by card.' That is clear context for invocation, but no alternatives or when-not conditions are named (e.g. when to use get_balance or get_price_quote instead), 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.

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

Annotations already declare a non-read-only, non-destructive, non-idempotent, closed-world operation, so the bar is lower; the description still adds substantive context beyond them: the link is private, valid for 60 minutes, sends nothing, and requires the user's account. These are auth, lifecycle, and side-effect details the annotations do not convey.

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

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

Three compact sentences, front-loaded with the trigger condition and followed by the lifecycle and handoff. No filler; every clause carries decision-relevant 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?

With no output schema, the description covers the return artifacts (URL to give the user, upload_id for create_letter), validity window, side effects, and auth requirement. An agent has everything needed to call it and act on the result.

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 and schema coverage is 100%, so there is nothing for the description to disambiguate; baseline is 4. It usefully explains what the caller supplies downstream (upload_id to create_letter) even though no input is required.

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?

It names a specific verb and resource ('Creates a private upload page') and precisely scopes it: a PDF resident on the user's own device that cannot be passed as URL or base64. This cleanly distinguishes it from sibling tools like upload_document 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?

Explicit trigger ('when the user wants to post a PDF that is on their own device and cannot be passed as a URL or base64') plus the downstream handoff ('pass upload_id to create_letter'). The agent knows both when to call it and what to do with the result.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, and the description goes well beyond them: crop 'removes everything inside the margin band, so that content is NOT printed', the original upload is kept, and re-calling with the other mode replaces the earlier fix. It also discloses a lifecycle constraint not in annotations (fails once the letter is paid), which is exactly the kind of context the agent needs before invoking a destructive fix.

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 triggering condition and mode semantics, and each sentence carries a distinct constraint (destruction, reversibility, lifecycle, escalation). It is dense — several clauses packed into long sentences — but 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, non-read-only operation with no output schema, the description covers what gets removed, what is preserved, reversibility, the paid-letter precondition, and the auth requirement. Nothing an agent needs to call this correctly 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% and the mode enum is already fully documented in the schema, so the baseline is 3. The description earns extra credit by adding behaviour the schema does not: how shrink centres pages ('US Letter for a US Letter PDF, else A4') and how mixed PDFs that already fit on A4 keep their placement.

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 (fix) and resource (document margins) and pins the exact trigger condition: an uploaded PDF that fails the print check because content is too close to the edge or pages are not A4/US Letter. This distinguishes it from check_pdf_margins (the diagnostic) 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?

Explicit when-to-use (print check failure), when-not-to-use (not possible once the letter is paid), and an escalation rule (ask the user which mode they prefer when content touches the edge). It also specifies the precondition 'Needs the user's account', leaving little 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description still adds value by stating "Changes nothing" and the auth-ish precondition "Needs the user's account," plus listing the returned fields despite no output schema.

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

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

Three short sentences, front-loaded with the trigger condition, then output contents, then the side-effect/auth note. No filler and nothing redundant with 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 parameterless read with no output schema, the description supplies exactly the missing pieces: when to call it, what it returns (credit, currency, minimum top-up), and that it has no side effects. An agent has everything needed to 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?

Zero parameters, so the baseline is 4. The description adds the only meaningful input context — that the user's account is needed — which is implicit scoping rather than a formal parameter. Nothing further is required.

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 the prepaid credit balance) and enumerates what comes back: credit, account currency, minimum top-up. This is unmistakable against siblings like create_topup_link or get_price_quote, which serve different purposes.

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 concrete triggering conditions: the user asking about prepaid credit, and checking coverage before sending a letter. That is clear context, but there is no explicit when-not guidance or named alternative for the related money question (top-up vs. price quote).

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 non-destructive, so the safety profile is covered; the description goes beyond them by asserting 'Changes nothing' and adding an auth requirement ('Needs the user's account') plus the return fields. It does not mention error behavior for an unknown reference or whether an unauthenticated call fails, so it is not exhaustive.

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 dense sentence front-loads the usage trigger and then packs the return fields, with 'Changes nothing. Needs the user's account.' as short trailing constraints. Every clause earns its place; the long parenthetical status list makes it slightly heavy but still readable.

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 no output schema, the description carries the return-value burden and does so by naming status (with its full value set), tracking number, and price. Combined with annotations covering safety and the 100%-covered schema, an agent has enough to call this correctly; only error/not-found behavior is unaddressed.

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

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

Schema description coverage is 100% and both parameter descriptions already state the formats and 'Pass letter_id or reference.' The description merely restates this optionality ('Look up by letter_id or reference (PM-XXXXXX)'), adding no precedence rule or extra meaning, so the 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 (retrieve a letter) and enumerates exactly what is returned: status, tracking number, price. The singular, instance-scoped framing ('a letter they created here', looked up by letter_id or PM- reference) is clearly distinguishable from create_letter, compose_letter, and list_letters 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 a concrete trigger ('when the user asks about a letter they created here') and the two accepted lookup keys. It stops short of naming alternatives or stating exclusions (e.g., use list_letters for multiple letters, create_letter to make one), so it is clear context rather than a full routing rule.

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 mark it read-only, idempotent and non-destructive, but the description goes well beyond: VAT treatment incl. reverse charge for EU business customers, works without sign-in, currency conversion via ECB rate plus margin, and the exact registered-mail semantics. These are meaningful behavioral details not derivable 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-loaded with the usage trigger, then packs return contents and caveats efficiently. It is dense and fairly long, but nearly every sentence (VAT, registered definition, currency, Europe posting) 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?

No output schema exists, but the description enumerates what is returned: exact total incl. VAT, line items, envelope, postal size class and zone, and typical delivery time. Combined with the when-to-use framing, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the currency conversion and registered-mail meaning, which mostly duplicates the schema's own parameter descriptions (e.g. postal_code island caveat, envelope recommendation), adding limited new value beyond the structured fields.

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: a price quote for sending a physical letter by post, including registered mail. It explicitly excludes email, fax, parcels and postcards, and the scope (printed/posted in Europe) distinguishes it clearly from compose_letter, create_letter, send_letter and get_balance.

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?

Front-loads the trigger condition ('Use this when the user asks what it costs to send a physical letter by post') and names out-of-scope cases (email, fax, parcels, postcards). It clarifies that no sign-in is needed and disambiguates 'certified'/Einschreiben/lettre recommandée/carta certificada, leaving little 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 readOnly, idempotent and closed-world, so the safety bar is low. The description adds real context beyond them: it works without sign-in and covers letters only, not parcels — useful constraints for an agent. It does not describe response format or pagination, but no output schema exists so this is a minor gap.

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 short, front-loaded sentences: usage condition first, then the two parameter modes, then behavioral constraints. No filler and every sentence adds usable 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 read tool with no output schema, the description covers when to use it, both parameter modes, and the returned fields (zone, prices, delivery time). Return values are only sketched, but that is acceptable given the tool's simplicity.

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 single optional country parameter and its ISO alpha-2 format are fully documented in the schema. The description restates the behavioral consequence of omitting or providing the code, which is helpful but largely mirrors what the schema already says; 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 (list destination countries) and distinguishes itself from siblings like get_price_quote by describing the postal-eligibility question it answers. An agent can tell what it returns and how it differs from letter-composition or pricing 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?

Gives explicit when-to-use triggers (user asks whether a letter can be posted to a country, or which countries are reachable) and clarifies the with/without-country split. It does not name alternative tools for related questions, 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 readOnlyHint=true, idempotentHint=true and destructiveHint=false, so 'Changes nothing' is largely redundant. The description still adds value beyond the annotations by disclosing the authorization requirement ('Needs the user's account') and the per-letter return fields an agent can expect without an output schema.

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

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

Four short sentences, zero filler, with the usage trigger front-loaded before the return, safety and auth notes. Nothing is repeated that the reader doesn't need at call time.

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 no output schema, the description compensates by naming the returned fields, and it covers the trigger, filter, safety profile and account requirement. An agent has everything needed to decide to call this and to interpret the result.

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%: both limit (default 10, max 50) and the status enum are fully documented in the schema. The description only restates 'optionally filtered by status' and 'recent,' adding no format or semantics beyond what the schema already provides, so the 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?

The description names a concrete verb and resource with scope: seeing 'recent letters, optionally filtered by status,' and it enumerates the returned fields. It separates itself in spirit from get_letter (single letter) by emphasizing a plural, filtered listing, but it never names that sibling 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?

It states a clear trigger — 'Use this when the user wants to see their recent letters' — and notes the optional status filter. There is no explicit when-not guidance (e.g., use get_letter for one specific letter), so it stops short of the top band.

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, it discloses that sending charges prepaid credit, releases the letter to print, and can only be cancelled before production starts. It also explains low-credit payment links, PAPER_CHOICE_REQUIRED and SENDER_DETAILS_REQUIRED failures, and that sender details are saved before paying.

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 main use case and every sentence carries operational guidance for a high-stakes payment action. It is dense and could be structured with bullets, but it is appropriately sized for the complexity and is not padded.

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?

It covers the essential behavior for a destructive, credit-charging, open-world tool: prerequisites, legal acceptance, payment handling, cancellation limits, print-channel limits, sender-detail collection, and failure modes. Given the absence of an output schema, it also explains that low credit returns a payment link in the result.

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 baseline is 3, but the description adds operational meaning for paper_size and sender: when paper_size is required, the recommended A4 choice, and that sender details are only needed while the account lacks them. Much of this is already in the schema, but the failure-code context adds value.

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 first sentence states a specific verb and resource: send a confirmed draft letter for printing and posting, paid from prepaid credit. It clearly scopes the tool against siblings by mentioning cancel_letter for cancellation and excluding email, fax and parcels.

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 preconditions: the user must have confirmed the specific draft, agreed to the Terms, and agreed to immediate printing. It also states when not to proceed by requiring that confirmation and by restricting the tool to paper letters rather than other channels.

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 (readOnlyHint=false, openWorldHint=true, idempotentHint=false), but the description adds material context beyond them: it stores the file in the account, requires the user's account, 'Sends nothing' (clarifying no letter is dispatched), and returns document_id for the downstream create_letter step. The A4/US Letter print-check explanation is tangled but genuinely discloses what the tool computes.

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 when-to-use and alternatives are front-loaded well, but the parenthetical about printed_on, compliant, all_pages_a4, and us_letter_note is dense, circular, and hard to parse. That clause costs more attention than it earns.

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 no output schema, the description still explains the return value (document_id for create_letter), the auth requirement, the no-send guarantee, the alternative tool, and the remediation path. 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 description coverage is 100%, so pdf_url, file_name, and pdf_base64 are already fully documented in the schema. The description adds no syntax or format detail beyond that, 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 and resource ('upload_document' stores a PDF in the user's account, runs a print check, and returns document_id for create_letter) and distinguishes itself from the sibling create_upload_link for on-device files. An agent can identify the tool's role 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 names the trigger ('when the user already has a PDF... that should be printed and posted'), the alternative for a different input source ('For a file on the user's own device, use create_upload_link instead'), and the failure path ('call fix_document_margins or ask the user for a corrected file'). This is the strongest kind of routing guidance.

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