Print and Mail Company

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

Annotations declare destructiveHint=true and idempotentHint=true, and the description adds genuinely new behavior: the credited refund, the irreversibility boundary for printed/posted letters, the account requirement, and the confirmation-before-action rule. These are consequences an agent needs that the annotations alone 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?

Front-loaded with the usage condition and broken into short clauses, with no filler sentences. It is slightly long, but each clause carries a distinct constraint (refund, recall limit, sibling disambiguation, confirmation).

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 strong annotations and no output schema, the description covers eligibility, effect (credit refund), and the confirmation requirement, which is close to complete for a single-parameter mutation. What is missing is the shape of the result/error when a letter is already in production.

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 sole parameter letter_id has 0% schema description coverage, so the description must carry the burden and largely does not — it never states the ID's format or provenance (e.g., from list_letters or create_letter). It only implicitly narrows which letters are eligible (drafts or pre-production paid letters on the user's account).

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 (cancel a letter created here) and immediately scopes it to drafts or paid letters not yet in production. It also disambiguates from the nearest confusing sibling by noting this does not cancel a user's contract with a third party, which is compose_letter's job.

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 gives the trigger (user wants to stop a letter created here), the exclusions (already printed or posted cannot be recalled), and the alternative route for contract cancellations via compose_letter. It even prescribes the interaction step: 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 cover readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds meaningful context: the file is not stored, nothing is sent, and it works without sign-in. It does not mention rate limits or how large a base64 payload error surfaces, which keeps it short of a 5.

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

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

Front-loaded trigger followed by capability, privacy, input forms, and the fix path; every sentence carries information. The first sentence is long and slightly run-on, costing a point.

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 ('lists the pages that need changes'), and it covers auth, privacy, input modes, and the fix workflow. A reader could still wonder what a passing check returns, which is the only notable gap.

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

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

Schema description coverage is only 50% (pdf_url is bare), and the description compensates by stating the URL must be public and https and that base64 is an alternative input, both of which are meaningful constraints beyond the schema. It does not add anything about the absent 'required' relationship between the two inputs.

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 action (verifies A4 page size and required free margins on every side) plus the return (lists pages needing changes), and explicitly names sibling tools (upload_document, fix_document_margins) so it is distinguishable 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 condition ('when the user has a PDF they want printed and posted and it should be checked first') and an explicit alternative for the adjacent need ('To fix a failing PDF, upload it with upload_document and use fix_document_margins'). Nothing is left 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?

Goes well beyond the annotations: it discloses that nothing is sent or charged, that it produces a draft with the exact price, that the user's account is required, and that the sender can be in any country. It also describes the rendering output (A4, DIN 5008 blocks) and print-check behavior, which the safety 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?

Front-loaded with the when-to-use trigger and use cases, then the behavior and workflow. Dense and mostly waste-free, though the parenthetical layout list and formatting notes make it longer than strictly necessary.

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 14-parameter, nested-object tool with no output schema, it covers the essential workflow, cost transparency, auth requirement, and body formatting. It omits explanation of a few optional fields (envelope sizes, duplex, color), but these are minor for correct invocation.

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 64%, so many fields (envelope, duplex, color, references, date, place) are documented by the schema. The description adds useful meaning for two things the schema does not: body mini-markup support (paragraphs, '- ' bullets, '1. ' lists, **bold**) and the purpose of registered mail. This is better than a bare baseline but does not fully compensate for the uncovered 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 ('write a new paper letter from text') plus concrete use cases (cancel a contract, complaint, formal notice). The scoping phrase 'from text' and the explicit downstream step 'call send_letter' distinguish it from create_letter and send_letter among the siblings.

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 when-to-use trigger with examples and embeds the follow-up workflow ('show the user the draft and the total, ask for confirmation, then call send_letter'). It does not explicitly name or exclude the closely named sibling create_letter, leaving the text-vs-other-source distinction 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 non-readOnly, non-destructive, non-idempotent, but the description adds substantive behavior: nothing is sent or charged, a draft is created with a total in the user's currency, the account is required, and every envelope carries the company return address so the user's own address goes in the document. It does not cover draft persistence/expiry or duplicate-call behavior, keeping it short of a 5.

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

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

A single dense paragraph that is front-loaded with the use case and disambiguation, and every sentence carries information. It runs long and packs several distinct ideas (synonyms, pricing, return address, auth) into one block, which slightly harms scanability.

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 draft-creating mutation with no output schema and a nested required recipient object, the description covers the workflow, pricing, non-charging, auth need, and the hand-off to send_letter. Minor gaps remain around optional print parameters (envelope, color, duplex) and draft lifetime.

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 low (29%), so the description must compensate. It adds real meaning for document_id/upload_id (source and create_upload_link origin) and for 'registered' (international registered with tracking and signature). However color, duplex, and envelope are never explained, leaving several parameters to the schema alone.

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

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

States a specific verb and resource ('Creates a draft with the exact total in the user's currency') and immediately distinguishes itself from send_letter. The registered/einschreiben/recommandée synonym mapping makes the intended scope unmistakable.

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 condition (uploaded PDF plus recipient address, wanting mail posted) and routes the agent: 'call send_letter only after the user confirms.' This is exactly the when-to-use / when-to-call-the-sibling guidance 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?

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=false), so the description's job is to add context — and it does: it discloses that the tool only returns a link, charges nothing, the assistant cannot complete payment, and that the user's account is required. It does not describe link expiry or whether repeated calls return the same or different links, despite idempotentHint=true.

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, followed by what the tool returns and what to do with it. Every clause carries actionable information (who pays, no charge, account requirement) with no repetition of the schema or 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?

With no output schema, the description correctly compensates by explaining the return value (a payment-page link) and the handoff to the user. The single optional parameter is covered, and no behavioral or auth detail an agent needs to call this safely is missing.

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

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

Schema coverage is 100%, which sets the baseline at 3, but the description adds genuine meaning by framing the two modes: omitting letter_id adds credit, supplying it pays that specific draft letter. That clarifies the optional parameter's role in a way the terse schema string ('Pay this draft letter directly') does not.

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 (create a payment link) and immediately scopes it to two concrete outcomes: adding credit or paying one draft letter by card. It also distinguishes itself from near-siblings like create_upload_link by describing the artifact returned (a link to the payment page on printandmailcompany.com).

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 when to use it ('when the user needs to add credit, or to pay one specific draft letter by card'), and clarifies a common misuse case by noting the assistant cannot pay and calling it charges nothing. It does not name a specific alternative tool or a when-not condition, so it falls just short of the top bar.

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 already flag destructiveHint=true and idempotentHint=true, and the description enriches this with what is actually destroyed (crop removes content inside the margin band so it is NOT printed) and what is safe (shrink loses nothing), plus that the original upload is retained and re-calling replaces the prior fix. It also discloses the auth dependency and a life-cycle 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?

Front-loaded with the triggering condition, then mode semantics, then lifecycle and interaction caveats. Every sentence carries information, but the mode explanation is repeated from the schema verbatim, which is mild redundancy rather than 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 no-output-schema mutation tool with rich annotations, the description supplies everything an agent needs: trigger, mode trade-offs, destructive vs non-destructive outcomes, idempotent/replacement behavior, payment gating, and the need to consult the user. No material gap remains.

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

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

Schema coverage is 50%, with mode fully documented in the schema and document_id undocumented. The description compensates by explaining both mode values and their consequences (shrink scales/centres on A4; crop keeps 100% and cuts the margin band) beyond the schema's terse gloss, though it adds nothing about document_id's expected format.

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 frames the exact triggering condition: an uploaded PDF failing the print check due to edge proximity or non-A4 pages. This clearly distinguishes it from the sibling check_pdf_margins, which only inspects rather than repairs.

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

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

Explicitly says when to use it ('when an uploaded PDF fails the print check'), when it is unavailable ('Not possible once the letter is paid'), and how to route a decision ('ask the user which mode they prefer'). Prerequisites (needs the user's account) and re-invocation semantics are also stated.

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

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

Annotations already declare 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 readOnlyHint=true, idempotentHint=true, so the safety profile is covered. The description adds value by stating 'Changes nothing' (reinforcing read-only) and 'Needs the user's account' (an authentication requirement not in annotations). It doesn't cover rate limits or pagination, but those are less relevant for a single-item fetch.

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 three sentences, front-loaded with the main use case and return values, then lookup methods, then behavioral notes. Every sentence adds useful information with no redundancy.

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 no output schema and sparse annotations, the description covers the essential aspects: what it returns, how to look up, safety, and auth. It is nearly complete, though it could mention what happens if no parameters are provided or if the letter isn't found.

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%, so the description must compensate. It mentions 'letter_id or reference (PM-XXXXXX)', which explains the two parameters and gives a format example for reference. However, it does not state that both are optional or that at least one is needed, nor does it clarify that they are mutually exclusive alternatives.

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 (look up / get) and resource (letter), and enumerates the exact information returned: status with enumerated states, tracking number for registered mail, and price. It clearly distinguishes itself from siblings like list_letters and create_letter by focusing on a single letter's details.

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 trigger: 'when the user asks about a letter they created here', and specifies two lookup methods (letter_id or reference). It does not explicitly mention when not to use it or name alternatives like list_letters, but the context is sufficiently clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the returned total includes Luxembourg VAT, quotes are returned as line items plus envelope, postal size class, zone and typical delivery time, and the call works without sign-in. It also explains that currency conversion uses an ECB rate plus a margin, which is non-obvious behavioral detail an agent could not infer.

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 selection trigger, and each subsequent sentence adds distinct information (registered semantics, currency behavior, no-sign-in, exclusions). It is on the long side and slightly dense with parenthetical terminology, but there is little dead weight.

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

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

There is no output schema, so the description must carry return-value burden and does: exact total incl. VAT, line items, envelope, size class, zone and delivery time. Combined with auth behavior ('works without sign-in') and coverage boundaries, an agent has everything needed to call and interpret this 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?

With 75% schema coverage the schema already documents pages, country, duplex, postal_code and registered. The description still adds meaning the schema lacks: what currency conversion does and its rate source, why postal_code matters (Spanish/Portuguese islands), and the exact registered-mail semantics. color and duplex print options are only gestured at ('print options'), so it is strong but not exhaustive.

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 price quote for sending a physical letter by post) and immediately scopes it to snail mail including registered letters. It clearly separates itself from siblings like compose_letter, create_letter and send_letter by being purely a costing operation, and explicitly disclaims email, fax, parcels and postcards.

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?

Opens with an explicit trigger ('Use this when the user asks what it costs to send a physical letter by post') and closes with explicit exclusions ('Does not cover email, fax, parcels or postcards'). It also pre-empts a terminology ambiguity by mapping 'certified', Einschreiben, lettre recommandée and carta certificada onto the registered flag, so the agent knows when the registered path applies.

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, openWorldHint=false, so the safety profile is covered. The description adds valuable context: the tool works without sign-in, and it enumerates what data is returned in each mode (zone, price, delivery time). It does not explicitly state rate limits or freshness of the data, but for a simple read tool this is a solid addition beyond 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?

Four tightly packed sentences, each earning its place: when to use, behavior with/without the parameter, authentication, and scope limitation. Zero 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?

The tool is simple (one optional parameter, no output schema, strong annotations). The description covers usage intent, both operational modes, expected return content, auth requirements, and scope limitation. 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 100% and the single parameter's description already states 'ISO code for details of one country'. The description repeats the conditional semantics (with/without country) but adds no syntax or format details beyond what the schema provides. Baseline 3 is appropriate when the schema carries full parameter documentation.

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

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

States a specific verb (list) and resource (destinations), and frames the user's intent ('whether a letter can be posted to a country, or which countries can be reached'). This is clearly distinct from siblings like get_price_quote or 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?

Explicitly distinguishes the two modes: 'Without country: all destination countries... With country: that country's zone...'. Also states scope restriction 'Letters only, no parcels', which routes the agent away from parcel-related siblings like send_letter or get_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 cover readOnly/idempotent/destructive, so 'Changes nothing' largely restates them, but 'Needs the user's account' adds a genuine auth prerequisite not present in structured fields. It still omits ordering, pagination, and how the default limit behaves.

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, trigger front-loaded, with no filler. Every clause either routes usage, describes output, or flags a prerequisite.

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 usefully enumerates returned fields (status, recipient, price, tracking number) and notes the account requirement. It is thin on result-set size and ordering, which matters for a list tool with a capped default.

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%, so the description must carry parameter meaning. It explains the optional status filter, but the limit parameter (default 10, max 50) is never mentioned, leaving result-count behavior undocumented.

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

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

States a concrete verb+resource ('see their recent letters') and implies a collection rather than a single letter, which separates it from get_letter. It stops short of naming any sibling explicitly, so an agent must infer the list-vs-get boundary.

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

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

'Use this when the user wants to see their recent letters' gives a clear triggering condition, and 'optionally filtered by status' clarifies the variant case. No when-not conditions or named alternatives (e.g. get_letter for a single letter) are provided.

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?

Goes well beyond the annotations (destructive/non-idempotent) by disclosing credit payment, print release, the cancellation window, what happens on insufficient credit (payment link returned, assistant cannot pay), and the account prerequisite. This is exactly the extra context 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?

Front-loaded with the trigger condition and the credit/cancellation consequences; each sentence carries distinct information. It is dense rather than padded, though the terms/withdrawal aside is longer than strictly necessary.

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 behavior (payment link on low credit), the legal gate, and the account requirement, covering 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 coverage is 67%; confirm and user_accepted_terms are documented in the schema, but letter_id has no description anywhere. The description reinforces what 'confirmed' entails ('recipient, content and total price') and ties user_accepted_terms to the Terms and withdrawal waiver, adding meaning beyond the schema.

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

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

States a specific verb+resource ('printed and posted' letter) with explicit scope ('Posts paper letters only: no email, fax or parcels'). It also names the sibling it interacts with (cancel_letter), so an agent can separate it from compose_letter/create_letter without opening schemas.

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 preconditions: only call after the user confirmed a specific draft AND accepted Terms and immediate printing. Names the alternative path (cancel_letter, valid only until production starts), leaving nothing 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 only declare non-readOnly, non-idempotent, non-destructive, openWorld. The description adds material context beyond them: it persists the file to the user's account, performs an A4/free-margin print check, sends nothing, and requires the user's account (auth). It does not address repeat-upload/duplicate behavior, which is the one trait left implicit for a non-idempotent write.

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, then the effects, then the failure path and alternative, then the safety/auth notes. Every sentence carries a distinct, actionable fact with no repetition.

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

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

For a 3-param, no-output-schema tool, it covers purpose, effects, return value (document_id), auth, and alternatives. The remaining gap is that it does not clarify the exactly-one-of pdf_url/pdf_base64 requirement implied by zero required parameters.

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

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

Schema coverage is only 33% (just pdf_base64 documented), so the description does carry weight by naming the two input forms (URL vs base64). However it never mentions file_name, never states that exactly one of pdf_url/pdf_base64 is needed despite required parameters being empty, and adds no format or size detail beyond what the schema already says for base64.

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 a PDF'), plus the accepted input forms (public https URL or base64) and the end state (stored in the account, print-checked, returns document_id). It is clearly distinguishable from create_upload_link and fix_document_margins, which it names.

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 gives the trigger ('when the user already has a PDF'), the alternative for the on-device case ('use create_upload_link instead'), and the remediation path if the print check fails ('call fix_document_margins or ask the user for a corrected file'). This is a complete routing decision.

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