Agent Letter Desk

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

Annotations already declare destructiveHint/idempotentHint, and the description adds real semantics beyond them: prepared letters are cancelled instantly with nothing sent or charged, paid letters are fully refunded, printed letters cannot be cancelled, and removing one item from a batch invalidates the batch approval. The destructive consequences are spelled out precisely, with no contradiction of the 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 core purpose and the cancellation outcomes, then alternatives, then batch mechanics. A few fragments ('Also a greeting card.') are abrupt and slightly slowing, but almost every sentence carries an operational fact.

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 and the description still names the key failure result (TOO_LATE), which is the main thing an agent must handle. Coverage of refunds, contract vs. letter, and batch edge cases is thorough; only the terse greeting-card remark is left ambiguous.

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 already documents both ids and their formats, so the baseline is 3; the description earns more by adding the mutual-exclusion rule ('Then do not give letter_id') and the batch-approval consequence of cancelling a single item, which the schema does not state.

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 ('stop a letter of this service', 'cancelled') and immediately disambiguates from the sibling concern it is most likely confused with: 'This tool does not cancel a contract.' An agent can separate it from prepare_letter/send_letter 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?

Explicit when-to-use plus alternatives: contracts are cancelled by preparing a letter with prepare_letter instead, and batch scope is selected by passing batch_id. It also gives the exclusion condition (already printed → TOO_LATE) that tells the agent when the call will not succeed.

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 a non-read-only, open-world, non-idempotent call; the description adds real context on top: the message is e-mailed to support, the user receives a copy, a ticket number comes back, and secrets (passwords, card numbers) must not be included. It stops short of stating whether a failed send or a retry produces a duplicate ticket, which matters for a non-idempotent tool.

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 when-to-use clause, then behavior, then constraints, each as one short sentence with no filler. Every statement (topics, exclusion, confirmation, reference, secret handling) carries actionable information.

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

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

Covers trigger, scope, side effects, consent requirement, and the return value (ticket number), and an output schema exists for the full return shape. Nothing needed to invoke it correctly is missing for a 3-parameter mutation tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds decision logic beyond the schema — attach a reference only when the message concerns a single letter or order, and keep the message in the user's own words without credentials. That is genuine routing guidance rather than restatement.

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 (sends the user's message by e-mail to the support team), the outcome (returns a ticket number), and explicitly distinguishes itself from the nearest sibling domain ("Do not use it to write or mail a letter"). An agent can tell this apart from send_letter/prepare_letter without inspecting 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 the triggering condition (user has a problem or question support must answer), enumerates covered topics, names an explicit exclusion, and adds prerequisites (only send after the user agreed to the text). Alternative routing is covered by the write/mail exclusion.

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?

The annotations already declare a non-destructive, non-open-world, non-idempotent creation operation. The description adds useful behavior beyond that: it makes two drafts or one from photos, each draft is shown as the printed card front, a missing photos_decision returns needs_answer, and nothing is mailed or charged.

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 purpose and the key workflow. It is generally efficient, though it repeats draft-count and photo/style details that also appear in the schema.

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 12 parameters and an output schema, the description covers the critical preconditions, privacy restriction, and failure mode. It leaves detailed parameter workflows such as refine_of and scene_mode to the schema, which is acceptable because coverage is 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 description coverage is 100%, so the baseline is 3. The description still adds important meaning for subjects (use roles, include age only if the user gave it, never names) and photos_decision (required in every call; its absence produces needs_answer), plus it routes style selection through get_card_options.

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: make the picture for the front of a greeting card. It also clarifies the output form (2 drafts, or 1 draft from photos) and distinguishes itself from get_card_options by telling the agent to ask that tool's questions first.

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

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

It gives clear workflow guidance: first ask the open questions of get_card_options in one message, always include photos_decision, and treat needs_answer as a signal to ask the user and call again. It does not explicitly compare this tool to prepare_card or send_card, so it stops short of full alternative 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?

Beyond the destructiveHint and idempotentHint annotations, the description explains important consequences: default-address reassignment, the fact that a prepared letter keeps its own copy, and that the server will not save the deleted address again. This materially improves the agent's understanding of the operation's side effects.

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 usage condition, then the action and key behavioral consequences. Each sentence carries distinct, useful information with no 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?

Given the single required parameter, full schema coverage, existing output schema, and destructive annotations, the description covers the important behavioral details an agent needs. Nothing critical is missing 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 description coverage is 100%, and the schema already explains that sender_address_id comes from get_account. The description does not add parameter-level meaning beyond that, so the baseline score of 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?

The description states a specific verb and resource: remove a saved sender address and delete it from the account. It is clearly distinguishable from the sibling save_address tool and does not merely restate the title.

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

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

It gives clear usage context ('when the user wants to remove a saved sender address') and an explicit guardrail ('only after the user asks for it'). It does not name a specific alternative sibling tool, so it falls just short of full when/when-not/alternatives 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 cover the read-only, idempotent, non-destructive profile, and the description adds useful context: the sender is always the account holder, what account data is returned, and how to handle a missing saved address. It does not discuss permissions or rate limits, but those are less critical here given the 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 description is front-loaded with the primary use case and stays focused on account retrieval plus the missing-address branch. It is slightly longer than necessary because the greeting-card note about unread updates is tangential, but there is no serious 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?

With a rich output schema, full annotation coverage, and no input parameters, the description is complete enough: it explains the trigger, returned data, and the empty-address fallback path. Nothing essential to correct invocation is missing.

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

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

The tool has zero parameters, so there are no parameter semantics for the description to clarify. The baseline for zero-parameter tools 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 states a specific verb and resource: it returns the sender/account-holder details for mailing use cases. It distinguishes the tool from save_address by explicitly routing missing-address cases there, so an agent can identify its role among 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?

It gives an explicit trigger: use when the user wants to mail a letter, Einschreiben, or US Certified Mail. It also provides the fallback workflow: if no saved address exists, ask the user and then call save_address.

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 and destructiveHint=false, so safety is covered; the description adds real value beyond them with 'Nothing is prepared or charged', which tells the agent this is a pure information step distinct from prepare_card/send_card. The disclosed return contents (including the upload link and Christmas order dates) further describe what the agent will get back. It stops short of describing pagination or error conditions, but for a static-options lookup that 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?

The trigger condition is front-loaded, the payload list is compact, and the workflow instruction comes last where an agent will act on it. The enumeration of card occasions and payload fields is slightly dense but each item is decision-relevant, and there is no 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?

With an output schema present, the return-value recap is technically redundant, but here it doubles as guidance on what the agent can hand back to the user, and the 'call it first / then create_card_picture' ordering covers the multi-tool flow. Combined with the no-charge assurance, an agent has enough to invoke this correctly without consulting siblings.

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 parameters are enums with self-explanatory schema text (language, upload_purpose with 'reference' vs 'print'). The description only alludes to the upload link and picture brief, adding no syntax or defaulting detail beyond what the schema already states, 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+resource ('get card options' for mailing a greeting card by post) and enumerates the returned payload: card format, picture brief, text-front option, message limit, price, Christmas order dates and upload link. It also scopes the offering (Christmas, birthday, wedding, anniversary, baby, thank-you, condolence cards to people in the United States), which separates it from the letter-related 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?

It gives explicit entry conditions ('Use this when the user wants to mail a greeting card by post') and hard sequencing ('Call it first. Then call create_card_picture'), which routes the agent through the correct multi-step flow. What is missing is an explicit exclusion, e.g. that letters use list_letter_types or that non-US recipients are out of scope, so the when-not case must be inferred from the scope sentence.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds the critical non-obvious trait: this is an internal tool reserved for the card preview view. It also scopes the result to the first card only, not the whole batch. It does not say why the restriction exists or what happens if it is called anyway.

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, with the most decision-relevant information ('Do not call it') placed up front, followed by scope and return meaning. No 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?

An output schema exists, annotations cover safety, and the one parameter is fully described in-schema. The description supplies the only thing an agent still needs: that this tool is off-limits and why it exists.

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 batch_id parameter is documented in-schema with its UUID pattern and its origin ('from prepare_card'). The description adds nothing about the parameter, so 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 the specific resource (the rendering of the first card of a prepared card batch) and the verb (returns), so an agent can distinguish it from prepare_card or get_card_options. The phrasing 'how the first card ... is drawn' is slightly vague about whether this is a layout/render preview versus card data, which keeps it from a 5.

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

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

It gives explicit negative guidance — 'Only the card preview view calls this tool. Do not call it.' — which is a rare and unambiguous when-not statement. It stops short of naming what an agent should call instead for card preview data, so it is clear context without a full alternative routing.

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 and destructiveHint=false, so the safety profile is fully covered and the description is consistent with it. Beyond that it discloses the status vocabulary and which tracking fields appear per state (handed_over_at, delivered_at, returned_at), which is useful, but it duplicates return-value content the output schema already carries rather than adding behavioral context such as refresh/polling timing or what an 'unknown'/'unresolved' status implies for retries.

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 usage trigger is front-loaded and the mode split (single vs batch) is clear, with no filler sentences. It is somewhat long because it enumerates return fields that the output schema already defines, which is the only 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 read-only status tool with an output schema and fully documented parameters, the description covers the intent, the status vocabulary, the two modes and the conditional fields. The remaining gap is that both parameters are optional, so the definition never says what the tool returns or whether it errors when neither letter_id nor batch_id is given.

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 both parameters already document themselves, including the 'then do not give letter_id' exclusivity note. The description reinforces only batch_id ('For a batch, give batch_id') and never mentions letter_id in prose, nor does it explain what happens when neither optional parameter is supplied. Baseline 3 is appropriate where the schema does the heavy lifting.

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

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

States a specific verb and resource (returns the status of one letter, or a whole batch) and anchors it to the user intent ('asks if a letter was mailed, handed to the post or delivered'). It also enumerates the possible statuses and the returned payload shape, so an agent can tell it apart from list_letters or get_card_view 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?

The opening sentence gives a concrete when-to-use trigger, and the closing sentence explains the routing between the single-letter mode (letter_id) and the batch mode ('For a batch, give batch_id'). It never names an alternative sibling such as list_letters for bulk listing without status, so there is no explicit exclusion 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 state readOnly/idempotent/non-destructive/closed-world, so the description's added value is the ordering guarantee ('newest first'), the returned field set, and the semantics of has_unseen_updates as an unread-events marker. It stops short of saying whether reading the list itself clears that flag, which is the one behavioral question an agent might still have.

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 the payload, then cross-references; nearly every sentence carries signal. The greeting-card and batch asides are terse but slightly clipped in phrasing ('batches sums up each batch'), which costs a bit of polish rather than length.

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-filter list tool with an output schema, the description covers trigger, ordering, field inventory, and sibling routing. Remaining gaps are minor: no pagination/truncation guidance and no note on whether the read affects has_unseen_updates.

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 (limit), and the schema already documents it at 100% coverage including default and maximum. The description adds nothing about paging or what happens when the limit truncates a large letter history, so 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 (list/returns) plus resource (letters of the user), with an explicit trigger context ('user asks about earlier letters by post or Einschreiben'). It also distinguishes itself from the sibling that reads details: 'Call get_letter_status for its events.'

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 when-to-use example ('which letters went out last month') and routes the agent to get_letter_status for event timelines, so the split between list and detail tools is explicit. It also clarifies that greeting cards appear in results, preventing a wrong assumption about the dataset.

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 safe, idempotent, closed read, so the description is free to add the parts not in metadata: what the response contains (sample-based example letter, the facts to ask the user, verified recipients, notes) and the branch that yields postal services/prices versus a price index. No auth or pagination notes, but nothing contradicts the 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 activation condition, then return contents, then the with/without-country branch, then the exception. Dense but every clause carries routing or payload information; only the country-branch sentence slightly overlaps the schema.

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 an output schema exists, the description does not need to enumerate return fields yet still characterizes them usefully, and both optional parameters' effects are explained. A mention of the sibling tools this is paired with (e.g. prepare_letter) is the only notable omission.

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 baseline is 3, but the description adds real semantics: 'With a country: its guides, postal services and prices. Without: an index with prices' explains the optionality of country in behavioral terms rather than just restating the enum. guide_id is only covered by 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 concrete verb and resource ('find letter guides' / returns letter guides) plus the scope of use cases (Kündigung, Widerruf/Rücktritt). It implicitly separates itself from list_letters and prepare_letter by describing the guide content, but no sibling is named, so routing still requires a small inference.

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 needs a formal letter by post: a cancellation or a withdrawal' gives an explicit activation condition, and the closing sentence gives a de-selection condition (letters without a guide, e.g. defect notice, Beschwerde, GDPR request). It stops short of naming the alternative tool to use in that case.

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 the meaningful behavioral detail: results are verified addresses with provenance (page and date), and stale entries are flagged 'unverified' with a note. It does not say what an empty or unmatched query returns, but the verification-status semantics are genuinely additive.

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, front-loaded with the trigger condition, then result semantics, then scope, then the exclusion. Every sentence earns its place, though the coverage list and the exclusion could be tightened into one clause.

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?

Output schema exists and annotations cover the safety profile, so the description only needed to cover selection context and provenance semantics, which it does. The one gap is that all three parameters are optional yet the description never says what a call with no filters returns.

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 each parameter is already documented with examples and enum meanings; the description only implicitly echoes the query and country dimensions via the company-category and Austria/Germany lists. Baseline 3 applies when the schema carries the weight and the description adds nothing operational beyond it.

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 verified postal addresses') plus what each result carries: the page where it was read and the date. It also scopes the domain (Austrian/German phone, energy, Rundfunkbeitrag, TV and fitness companies), which separates it from siblings like save_address, delete_address or list_letters.

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 a letter goes to a known company') and an explicit non-trigger, routing other recipients (landlord, insurer, authority) to the user's contract, order, invoice or recipient letter. Nothing is left to inference about when this lookup is appropriate.

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 mark this as non-read-only but non-destructive, and the description supplies the crucial context the annotations cannot: 'Nothing is mailed or charged' (a free preview that creates a batch) and that a re-batched call produces a new batch_sha256 requiring re-approval. These are exactly the behavioral traits an agent needs before invoking a mutating-but-not-finalizing tool.

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

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

A single front-loaded paragraph: use case first, then inputs, then return values, then the exclusion. It is dense but every sentence carries distinct information (returns, nothing charged, e-card exclusion). Minor room to tighten the input enumeration since the schema covers 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?

Covers what it returns ('the batch, the price, each card and the notes'), the no-charge guarantee, the batch-growth path, and the negative scope, and an output schema exists to carry return structure. 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 already documents every field in depth, so the baseline is low. The description still adds meaning beyond the schema by stating the batch_id re-call workflow and the 'at most 100 cards in a batch' ceiling, which the schema does not state, plus the design_id-vs-front_text either/or.

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 specific condition-of-use verb phrase ('mail a greeting card to people in the US') and names the resource and scope. It explicitly excludes e-mail and e-cards, which cleanly separates it from send_card and prepare_letter siblings 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?

Gives explicit when-to-use ('when the user wants to mail a greeting card'), when-not ('Do not use it for e-mail or e-cards'), and the branching path for volume ('For more recipients, call it again with batch_id'). The schema further routes to create_card_picture, get_card_options, and get_account, so alternatives are discoverable.

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 readOnlyHint=false, destructiveHint=false, and the description adds the crucial behavioral facts that go beyond them: output is a PDF preview, nothing is mailed and nothing is charged. It stops short of describing the approval/send step that must follow before anything actually goes out, which is the main behavioral gap for a preparation tool.

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?

Six short sentences, front-loaded with the core trigger, then examples, then the preview/no-charge guarantee, then the exclusion. Every sentence adds a distinct decision fact; nothing repeats the name 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?

For a 25-parameter tool with an output schema and fully documented parameters, the description covers purpose, scope, cost/send side effects and exclusions adequately. It omits notable behaviors implemented via parameters (multi-recipient batches, resend_of, replaces_letter_id, content-refusal rules), though those are documented in the schema.

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% across 25 parameters, so the schema carries all field-level meaning. The description adds no parameter guidance at all (no mention of required purpose/paragraphs, sender vs recipient, style/layout interplay); baseline 3 applies when the schema does the heavy lifting.

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

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

The description gives a specific verb+resource (prepare a paper letter for post) and enumerates the concrete letter types (Mängelanzeige, Einspruch, Kündigung, personal letters). It implicitly separates itself from send_letter with 'Returns a PDF preview. Nothing is mailed or charged,' but never names the sibling, so the routing is inferable rather than explicit.

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 with a rich set of real examples, an explicit trigger ('When the user asks for a letter text, offer to mail it'), and an explicit exclusion ('Do not use it for e-mail or chat messages'). An agent can decide invocation without opening the schema.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real context: saving with an id overwrites a saved address, addresses are only stored after user consent, and 'The sender name is always the name of the account holder.' It still doesn't say what happens to fields omitted during an update, which matters for a destructive-hinted mutation.

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 trigger sentence is front-loaded and the rest is short and dense. The trailing sentence about only the user changing the name on the account page is user-interface trivia that competes with the operational guidance for attention.

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

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

With an output schema present and full schema coverage, the description covers the essentials: purpose, consent gating, add-versus-overwrite semantics, and the account-name override. Only the effect of a partial overwrite of an existing address is left unexplained for a nested three-parameter mutation tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description explains the add-versus-change meaning of sender_address_id and the name-is-account-holder rule, but both points are already spelled out in the schema property descriptions, so added value over structured data is marginal.

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 plus the two modes: 'Adds a sender address to the account, or changes a saved address (with sender_address_id)'. The add-versus-change split also separates it from delete_address and get_account in the sibling list.

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 gives their postal address for letters, or wants to change a saved sender address') and adds a consent precondition: 'Save an address only after the user gave it or agreed to it.' It routes the agent to get_account to obtain a sender_address_id, but never names delete_address as the tool to use for removal.

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 destructive=true, openWorld=true and idempotent=true; the description adds the operationally critical context of cost ('costs the approved total') and irreversibility ('cannot be undone after printing starts'). The stated refusal of a second send and of changed batch/price is consistent with idempotentHint and gives the agent a clear recovery path.

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: purpose, cost, irreversibility, preconditions, then instructions. A few phrases are cryptically terse ('ORDER_REQUIRED: give the user the order_url'), and 'Refuses... a second send' partially duplicates 'Do not call send_card again'.

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, money-spending action this covers preconditions, refusal behavior, the confirmation handshake, and the follow-up requirement to surface order_url. With an output schema available and full schema coverage, nothing essential 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 the schema already defines every parameter including the conditional distinct_messages rule and allow_duplicate. The description mostly restates which values to pass ('Give batch_id, batch_sha256, confirmed_count...') rather than adding new 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 ('mails the greeting cards of a batch') and anchors it to a named sibling ('from prepare_card'), so an agent can tell it apart from prepare_card and the letter tools. The irreversible-after-printing scope is stated in the same opening block.

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 after the user approved the picture, the message, each recipient and the total price, in a later answer than prepare_card'), explicit refusal cases, and an explicit terminal instruction ('Do not call send_card again'). Nothing is left to inference about when this tool should fire.

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

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

Annotations already declare destructiveHint=true, so the description's 'Cannot be undone after printing' adds the crucial timing detail rather than restating the flag, and it layers on the human-approval gate and the zero-price constraint. It does not cover the batch-vs-single execution path or error behavior, which keeps it off 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?

Very short and front-loaded: purpose first, then the qualification, then the alternative, then the precondition and the irreversibility warning. Every sentence carries a distinct constraint; nothing is padding.

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

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

With 9 parameters, rich annotations, and an output schema, the description covers the decision-critical parts: eligibility, the bypass route, and the approval gate. Batch handling and the allow_duplicate escape hatch are only in the schema, a minor gap for an otherwise complete definition.

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 field descriptions already explain batch_id/letter_id exclusivity, the sha256, and confirmed_price_cents. The tool description adds only the framing that the confirmed price is 0 for a resend, which the schema also states, so this is the baseline-3 case where the schema does the heavy lifting.

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

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

States a specific verb and resource ('Mails a prepared letter by post') and immediately bounds the scope to free resends, which separates it cleanly from prepare_letter and send_card. An agent knows what this does and what it does not do 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 explicit when-to-use (free resend via resend_of, price 0), explicit when-not ('Do not call this tool for a letter with an order_url'), an alternative action (hand the user the order_url), and a sequencing precondition (only after the user approved preview and recipient, in a later answer than prepare_letter). 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?

Annotations already declare readOnly=false, idempotent=true, destructive=false and openWorld=false, so the safety profile is covered. The description adds real value on top: it discloses the return behavior ('Returns all preferences') and imposes a consent prerequisite (only after the user asks), which the annotations do not express.

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 usage trigger, and the closing pointer to get_account is well placed. There is mild redundancy: the first sentence's 'pages and e-mails in English or German' is restated almost verbatim by the second sentence's field enumeration, so one sentence 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 two-parameter, zero-required mutation tool with an output schema and full annotation coverage, the description is nearly complete: it states the mutation target, the consent rule, and the read alternative. The only material gap is whether a partial update (one field supplied) is permitted and what happens to the unspecified preference, which matters given both parameters are optional.

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 properties carry enum descriptions ('en: English. de: German.' / 'true: the user gets an e-mail when a letter goes to the post...'), so the description's restatement of 'en or de' and 'on or off' adds nothing beyond structured data. The one thing it could clarify and does not is whether omitting a field leaves that preference untouched. 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?

Names a specific verb and resource ('Changes the preferences of the account') and enumerates exactly which two preferences it touches: page/e-mail language (en/de) and letter-status e-mails (on/off). It also distinguishes itself from the read path by noting 'get_account also shows them', so an agent can route between writing and reading preferences 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 opening sentence gives concrete user-intent triggers ('user wants pages and e-mails in English or German, or wants e-mails about letters on or off') and adds a meaningful constraint: 'Change a preference only after the user asks for it.' The alternative for viewing preferences (get_account) is named, though the description never states a 'do not use when' condition or that omitted parameters remain unchanged.

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, the description explains refund behavior, that the server tries to stop the letter, when the withdrawal right ends, the two-step confirm process, and that the user receives an e-mail. This adds substantial operational context for a destructive, externally visible action.

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 purpose and the key alternative, then proceeds through consequences and the confirmation workflow. Every sentence carries useful operational 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 destructive withdrawal tool with refund and timing implications, the description covers the important prerequisites, consequences, and confirmation flow. An output schema exists, so return-value details need not be repeated.

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. The description adds meaningful semantics for confirm by explaining that the first call should omit it and the second should set it to true after user confirmation.

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: withdrawing from a paid letter order of this service. It also explicitly distinguishes this tool from prepare_letter, which is used to write a withdrawal letter to another company.

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

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

It gives explicit when-to-use guidance, a clear when-not-to-use case, and names the alternative tool prepare_letter. It also specifies the required two-step confirmation workflow.

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