Human Mailbox

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

No annotations are provided, so the description carries the full burden. It does disclose the important fact that this moves money ('and pay it') and requires quote_ready state, but says nothing about irreversibility, idempotency, what happens if the order was already accepted, or failure modes.

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

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

One sentence, front-loaded with the action and effect, zero filler. The precondition is packed into a parenthetical rather than wasted prose.

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?

This is a financial mutation with no annotations, no output schema, and an undocumented id parameter. The description should say more about outcomes, idempotency, and conflicts with pay_item, but leaves those to inference.

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 50%: api_key is documented in the schema, while id is not. The description partially compensates by implying id is the order identifier subject to quote_ready status. That is useful but thin for a payment call where a wrong id is costly.

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 (accept) and resource (quoted price of an order), plus the effect ('pay it') and a precondition (status quote_ready). This is far more specific than the name alone, though it never names the nearest sibling (pay_item) to draw the 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?

The parenthetical 'status quote_ready' is an implied precondition for calling it, which is real guidance. But there is no statement of when-not to use it, no routing to pay_item/get_prices for orders not in quote_ready state, and no note on what to do if the quote has expired.

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?

With no annotations, the description carries the full burden. It does disclose one useful behavioral fact: the call returns a shipment_id that feeds request_action. However, it never explains what notifying the human actually means (immediate message? queued?), whether the shipment is persisted and listable via list_shipments, or how open_mode='never' 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?

Two tight sentences with the primary action first and the follow-up routing second. No filler, and the useful return-value hint is packed into a parenthetical.

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 tool with eight optional parameters, near-zero schema documentation, no annotations, and no output schema, two sentences are far too thin. The agent cannot tell why all parameters are optional, what happens if tracking/sender are omitted, or what the call returns besides shipment_id.

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?

Eight parameters with only 13% schema description coverage, yet the description addresses only 'tracking' ('tracking number helps') and says nothing about sender, carrier, expected_at, instructions, description, or the open_mode enum. The semantics of open_mode ('standard' vs 'same_day' vs 'never') are especially opaque and are the main thing an agent would need explained.

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 (announce an inbound shipment to the human) and names the sibling request_action that consumes the returned shipment_id. It does not distinguish itself from contact_human or send_message, which could plausibly overlap, but the core purpose is unambiguous.

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 context ('something is on its way') and explicitly hands off the follow-up case to request_action with the returned shipment_id. No when-not-to-use guidance or exclusions are offered, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden and does supply real behavior: credit costs, per-letter/per-parcel consumption, and the two payment paths (balance or inline x402). It omits the mutation's consequences — whether a repeat call charges again, whether purchases are refundable, and what happens if the balance is short.

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?

Two sentences, both earning their place: pricing catalog first, then the consumption rule and payment paths. Front-loaded with the decision-relevant information and free of 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 an unannotated purchase tool with no output schema, the description covers cost and payment adequately but leaves the agent guessing about return values (credits granted? invoice?), failure/retry behavior, and auth needs beyond the api_key escape hatch 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 coverage is 50% and only api_key is documented in-schema; the description compensates by annotating the bundle enum with prices for the three letters_* values. The same_day_10 and same_day_100 values are named but left with no price or explanation of when 'same-day' applies, so the compensation is partial.

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+resource: 'Buy a bundle of letter credits' with the concrete catalog enumerated. It is a clear prepaid-credits purchase, but it never distinguishes itself from siblings that also move money (top_up, pay_item, check_top_up), so the agent must infer that this one buys postage credits rather than adding balance.

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

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

Usage is implied by the credit-consumption rule ('Every arriving letter uses 1 credit, a parcel 3'), which tells the agent why it would buy, but there is no explicit when-to-use or when-not-to-use against top_up, check_top_up, or get_prices. No prerequisites or alternatives are named.

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

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

With no annotations, the description carries the full burden, and it does disclose the key side effect: paid money is returned to balance, and the operation only works before the order starts. It says nothing about irreversibility, whether the refund is immediate, permissions required, or what happens if the order has already started.

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 compact sentence with the action first and the refund consequence second. No filler, and the most important constraint is front-loaded.

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 tool with no annotations and no output schema, the description covers the action and main consequence but omits the identifier's meaning, failure behavior when the precondition is violated, and whether the refund is synchronous. Adequate but with clear gaps.

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%: api_key is documented in the schema but the required `id` has no description anywhere. The description never clarifies whether `id` is an order id or a request id, which is exactly the gap the low coverage requires it to fill.

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 an order") and adds a scope qualifier ("that has not started"). However, the tool is named cancel_request while the description says "order", and siblings include get_request/list_requests, so the request-vs-order naming leaves a small ambiguity about which resource is being cancelled.

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 phrase "has not started" gives an implicit precondition for when the tool applies, which is useful. But no alternative is named (e.g. what to do if it has already started, or whether contact_human/request_action are the fallbacks), so the agent must infer the when-not path.

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 openWorldHint=false, so safety is covered. The description adds useful auth context (ticket or api_key fallback), but says nothing about polling/waiting semantics for an asynchronous human reply, which is the main behavioral risk for this 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?

Two short sentences, front-loaded with what is returned and what to supply. No filler, though the parenthetical about api_key is slightly compressed to the point of ambiguity.

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 does state what comes back (status and answers), covering the return-value burden. It is missing only behavioral detail on pending inquiries and ticket provenance for a 3-parameter 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 only 33%: id and ticket are undocumented in the schema, and the description partially compensates by explaining the ticket-or-api_key alternative path. It still never says what the id refers to or where the ticket comes from, so the compensation is incomplete.

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 resource (an inquiry's status and answers) and explicitly ties it to its sibling contact_human, which is the tool that creates the inquiry. However, 'Status and answers of an inquiry' is a noun phrase rather than a clear verb, leaving retrieval slightly implicit.

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?

Implies the usage context by referencing contact_human, so an agent can infer this is the follow-up call after creating an inquiry. It does not say when not to use it, whether the inquiry must already exist, or what to do if the status is still pending.

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 openWorldHint=false, so the safety profile is covered and the description needn't restate it. What it does add is that the check covers two payment rails (Bitcoin, PayPal), implying async settlement, but it says nothing about what a call actually surfaces (paid/pending/expired) or whether repeated polling is expected.

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 sentence with no filler, which is appropriate for a narrow read-only check. It is arguably too terse given the unexplained 'id' parameter, but the sentence itself earns its place.

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

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

There is no output schema, so the description carries the burden of explaining what the check returns — and it doesn't. For a tool whose entire value is telling the agent whether a payment settled, leaving the possible result states (and what to do when still unpaid) unstated is a significant 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 coverage is only 50%: api_key is documented in the schema but the required 'id' parameter has no description anywhere, and the tool description never explains that it is the top-up identifier. An agent must guess whether 'id' is the top-up id, an invoice id, or a request id — a real ambiguity in a codebase full of id-bearing siblings.

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 ('Re-check') and resource (whether a Bitcoin or PayPal top-up was paid), so the agent knows this is a payment-status read rather than an initiation. The 'Re-check' framing hints at a counterpart to top_up, but it never names that sibling, so differentiation is implied 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?

'Re-check' implies this is called after a top-up has already been started, but there is no statement of when to call it (after top_up? while pending? on a poll interval?) and no explicit pointer to top_up as the initiating alternative. Usage must be inferred from a single word.

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?

With no annotations, the description carries the behavioral burden and does well: it states the tool works without an account, that a human usually answers within one business day, and that without api_key you get a ticket to read via check_inquiry. It leaves some behavior unstated, such as what changes when api_key is provided and whether a ticket is always created, which keeps it from 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?

The description is dense but front-loaded: account behavior first, then topic routing, then response expectations. It avoids fluff, though the parenthetical topic list makes it harder to scan than a short structured list would be.

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 and no annotations, so the description must cover purpose, usage, and follow-up behavior. It does most of that, including the ticket follow-up path and human SLA, and gives enough topic-specific guidance to call the tool correctly. The main gap is that several of the 10 parameters remain unelaborated.

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 40% across 10 parameters, so the description must compensate. It adds meaningful semantics for topic values and conditional fields like budget_eur, location/deadline implied by 'what, where, when', and method_wanted for payment_method, but it does not explain name, email, subject, or the exact role of several other fields. That is partial compensation, not full.

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 conveys that this is an inquiry-submission channel for non-standard orders, with the human-answer framing in the opening and SLA line. It does not explicitly say 'submit an inquiry to a human' in a single verb+resource phrase, but the topic list and title make the purpose clear enough. It also distinguishes itself from standard ordering and from the sibling check_inquiry.

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?

Usage is explicitly scoped to 'anything that is not a standard order' and then broken down by topic with concrete conditions: special_request for jobs not in the price list, is_it_possible before sending mail, payment_method when a payment method is missing. It also points to check_inquiry for reading the answer when no api_key is supplied. This is unusually clear routing guidance.

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

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

With no annotations, the description carries the full disclosure burden. It does add two genuinely useful facts: no account is required, and a follow-up notification occurs when the requested thing becomes available. It says nothing about whether this is a write, duplicate/idempotency behavior, or rate limiting, which is a meaningful gap for a submission 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?

The most decision-relevant fact ('No account needed') is front-loaded, and the rest is two compact sentences. The field enumeration is somewhat list-like but earns its place given the 0% schema coverage.

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 six-parameter submission tool with no annotations and no output schema, the description covers purpose, auth posture, and follow-up. It still omits what the agent gets back on success, how required vs. optional is resolved, and any deduplication behavior, which an agent needs before submitting on a user's behalf.

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 0%, so the description must compensate; it does enumerate all six fields (kind, name, email, country_wanted, use_case, found_via) and flags email as optional, which is better than nothing. But it gives no format or constraint guidance and, by only calling out email as optional, implies the others are required when the schema declares zero required parameters — leaving the agent unsure what a valid submission looks like.

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 action and artifact: leave a note capturing interest in something not yet offered (another country, a feature). The verb+resource are identifiable and the audience (agent vs human) is explicit. It does not name any sibling, but the 'not ready to register / not offered yet' framing implicitly separates it from register_mailbox and request_action.

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 triggering condition: use this when you are not ready to register or need a country/feature that does not exist yet. That is real guidance rather than a restatement of the name. No exclusion clause and no sibling is named, so the agent must still infer that contact_human or request_action are the alternatives for different needs.

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 openWorldHint=false, so the safety profile is covered. The description adds modest value by enumerating the returned facets (balance, address, counts), though it doesn't clarify whether this is strictly the authenticated caller's own record or how the aggregate differs from the narrower getters.

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 short sentence with no padding, and the key content is front-loaded. It is arguably too terse rather than verbose, but nothing is wasted.

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

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

With no output schema, the description carries the burden of describing return values, and it only lists facets ('balance, address and counts') without structure or format. For a simple one-param read tool that is minimally adequate, but it leaves the agent guessing about the shape of the response and its overlap with sibling getters.

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 api_key parameter is fully documented in the schema, including the header fallback. The description contributes nothing about the parameter, 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 verb 'get' plus 'account' identifies the resource, and the phrase 'balance, address and counts' hints at the payload. However, siblings get_balance, get_address, and get_summary cover the same ground, and the description never explains why an agent should prefer this aggregate call over those narrower ones.

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?

There is no explicit when-to-use guidance, no exclusions, and no mention of the alternative tools (get_balance, get_address, get_summary) that overlap with this one. Usage is only implied by the possessive 'Your account'.

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 establish this as a safe read-only tool. The description adds valuable behavioral detail beyond annotations: the address format, mailbox code placement, and the c/o name convention with an explicit warning never to invent a name.

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 two tightly written sentences with no wasted text. It front-loads the primary purpose and then adds the important style-specific formatting rule.

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 simple read-only getter with fully described parameters and safety annotations, the description supplies the remaining needed context: what the returned address looks like and how registration-oriented name formatting works. No output schema exists, but the description adequately explains the returned content.

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 parameter definitions are already documented. The description adds meaningful semantics for the "person" style, explaining the resulting name format and fallback behavior, which goes beyond the enum description.

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 clearly identifies the resource as the user's postal address for letters and parcels, including the mailbox code line. It is specific but does not explicitly differentiate from siblings such as get_account, though no close alternative is apparent.

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

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

It states when the address is useful—for letters/parcels and registrations needing a first and last name—and explains when to choose the "person" style. It does not list exclusions or named alternatives, but the usage context is 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 readOnlyHint=true and openWorldHint=false, so safety is covered, but the description adds nothing beyond a hint at the payload. It says nothing about authentication behavior (the api_key fallback), freshness of the balance, or whether transactions are paginated or truncated.

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 sentence with no filler or redundancy. It is efficient, though its brevity is also the source of the definition's gaps.

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 is the only place to explain what is returned, and 'recent transactions' leaves the window, format, and units undefined. For a tool whose entire value is the shape of its response, this is a significant 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?

There is only one optional parameter and the schema documents it fully (100% coverage), including the hm_... format and the Bearer-header fallback condition. The description adds no further parameter meaning, which is acceptable given the schema does all the work.

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 phrase 'Your balance and recent transactions' largely restates the tool name and title ('Balance') without a specific verb or scope. It never says what a balance is (account credit? money owed? codes?) nor distinguishes it from close siblings such as get_summary, get_account, or check_top_up.

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?

There is no indication of when to call this versus get_summary, get_account, or check_top_up, and no prerequisites or exclusions are stated. The agent must infer usage entirely from the name.

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 openWorldHint=false, so safety is covered. The description adds genuinely new behavioral information: photos and scans come back as viewable images, which is the only disclosure of return shape given there is no output schema. It stops short of stating error behavior for non-arrived items or whether access is scoped to the caller's account.

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 sentence that front-loads the purpose and appends the one fact an agent cannot get elsewhere (images are returned). No filler, no restatement of 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?

The read-only semantics are covered by annotations and the return content is covered by the description, so the essentials are present. However, for a tool whose required `id` is undescribed in both schema and description, and with no output schema, the definition leaves an agent guessing about the identifier and about non-arrived items.

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 50%: the api_key parameter is documented in-schema, but `id` has no description at all. The description says "one arrived item" which weakly implies id refers to an item, yet it never states the identifier format or origin. With the schema silent on the required parameter, the description needed to compensate and 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?

"Details of one arrived item" gives a clear verb (retrieve details), a specific resource (a single item), and a scope qualifier (arrived). The word "one" implicitly contrasts with the list_items sibling, but no sibling is named, so an agent must infer the distinction.

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?

Usage is only implied: fetching a single item's details. There is no "use when" statement, no mention of list_items as the alternative for enumerating items, and no note about what happens for an item that has not arrived. Adequate for a simple lookup, but nothing steers selection.

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 openWorldHint=false, so safety is covered. The description adds only the currency (EUR) and a rough scope of services enumerated, but says nothing about whether prices are static, per-country, or subject to the user's subscription/plan — relevant context for a pricing lookup.

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

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

It is short (one line) and front-loads the currency, but it is a run-on fragment with inconsistent structure: some items carry prices (mailbox 15 €, letter 5 €, parcel 15 €) while others (bundles, same-day, forwarding) are listed with no value, mixing categories and payment methods in 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?

There is no output schema, so the description carries the burden of describing the return value. It gestures at coverage (8 services, payment methods) but never states the shape of the response and leaves several listed items without prices, so an agent cannot fully predict what it will receive.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description does not need to explain inputs here.

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 text is a list of prices rather than a statement of what the tool does; there is no verb or object describing the action (e.g. 'returns the current price list in EUR'). Only the title 'Prices' and the leading fragment imply intent, so an agent must infer the purpose.

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?

No guidance on when to call this versus any of the ~30 siblings (e.g. buy_bundle, pay_item, get_subscription all touch pricing). No prerequisites, no exclusions, no alternatives named.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered. The description adds genuine value by disclosing the payload contents (result notes, tracking, files), but says nothing about behavior on an unknown id, permissions, or whether the tracking/files sections can be empty. With annotations carrying the safety profile, a 3 fits.

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

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

It is short and front-loaded, but it is a single fragment that omits the main verb, so the brevity reads as under-specification rather than efficiency. Nothing in it is wasted, but too little is there.

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 lookup tool with no output schema and an undocumented required parameter, the description should at minimum define the id and how the request/order distinction works. It instead only gestures at return contents, leaving the caller to infer the rest from the schema alone.

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 50%: api_key is documented in-schema, but the sole required parameter, id, has no description anywhere. The description does not clarify what the id identifies (a request, an order, an opaque handle) or its format, so it fails to compensate for the coverage gap.

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 sentence names the resource and its scope ('One order') and enumerates what comes back ('result notes, tracking and files'), which does distinguish a single fetch from the sibling list_requests. However, it is a noun fragment with no verb, and it silently renames the tool's 'request' to 'order', leaving the agent to guess whether those are the same entity.

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?

There is no when-to-use guidance at all: nothing says to prefer this over list_requests, nothing about how to obtain the required id, and no prerequisites or failure conditions. The only implicit signal is the word 'one', which the agent must interpret on its own.

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 openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context the annotations cannot carry — the 15 €/30-day price and that renewal draws from balance — but says nothing about what happens when the subscription is expired or unregistered.

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

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

One compact sentence with no waste, but it front-loads pricing rather than the primary purpose (reading status), and the colon-constructed ending reads as a note rather than a statement of function.

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 does well to name the returned fields (status, paid_until). However, it never enumerates possible status values or clarifies the outcome when no subscription exists, leaving a gap for a status-check 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?

Single optional api_key parameter with 100% schema description coverage, so the schema already explains the bearer-header fallback. The description adds nothing about the parameter, which is acceptable at this coverage level but is the baseline, not better.

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 is a fragment that names the resource (mailbox subscription) and the fields returned (status, paid_until), with the verb supplied only by the tool name. It is interpretable but does not state plainly 'returns the current mailbox subscription status', and gives no sibling differentiation.

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?

There is no explicit when-to-use guidance and no mention of the obvious alternatives (pay_subscription to renew, register_mailbox to create, get_balance to check funds). The pricing detail implies checking status before paying, but the agent must infer that.

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 openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds the content scope (which sections appear) but says nothing about the return shape, freshness/latency of the figures, or whether entities are truncated.

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 fragment with zero filler, and the time scope ('This month') is front-loaded ahead of the content list. It is terse to the point of being underspecified rather than verbose.

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-required-param read-only tool with no output schema, the description covers what categories come back, which is the main thing an agent needs. It omits return structure and any differentiation from the many sibling read tools, which is a real gap given a 31-tool namespace.

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 api_key parameter is fully documented in the schema, including the fallback condition for when the auth header cannot be sent. The description adds nothing beyond that, so the baseline of 3 applies.

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

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

The description enumerates the exact contents returned (costs by kind, budget used, subscription, open orders, mail, shipments) and time-scopes them to the current month, so an agent can tell this is an aggregated overview rather than a detail fetch. It stops short of naming a verb or explicitly contrasting itself with siblings like get_balance or get_subscription.

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?

There is no statement of when to call this versus get_balance, get_account, list_invoices, or the other summary-adjacent siblings. The 'overview' framing only implies that this is a starting point; the agent must infer it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful non-obvious behavior: unrevealed codes are masked to label plus last characters, while revealed ones return the full code — this tells the agent what it will and won't get back.

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?

Two tightly written sentences, zero filler, with the resource identity front-loaded and the masking behavior immediately after. Nothing to cut.

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

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

With no output schema, the description carries the return-value burden and does so for the key distinction (masked vs. full code). Minor gaps remain: no mention of pagination/ordering or how to obtain the revealed state, which is exactly what reveal_codes exists for.

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 optional parameter (api_key) and it is fully documented in the schema, including when it is unnecessary. The description adds nothing about it, but with 100% schema coverage the baseline of 3 applies.

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

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

The description names the resource precisely — gift card/voucher codes that arrived by mail — and explains the two content states (waiting vs. revealed). It does not, however, distinguish itself from the sibling reveal_codes, which is the most likely confusion point.

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?

There is no explicit when-to-use statement and no mention of when to call reveal_codes instead. An agent must infer that this tool lists and the sibling reveals, which is left entirely implicit.

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 establish that this is a read-only, closed-world operation. The description adds useful scope detail by saying results include full text and invoice-less payments, but it omits ordering, pagination, and response-format behavior.

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 single sentence is compact and front-loads the two key result categories. Every clause carries meaning, with no wasted text.

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 simple read-only list tool with one optional parameter and no output schema, the description gives the essential content scope. However, it does not describe the response structure, ordering, or whether the result set is bounded, leaving some burden on the caller.

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?

There is one optional parameter (api_key) and schema description coverage is 100%, so the schema already explains it fully. The description adds no parameter-specific meaning, matching the baseline of 3 when schema coverage is high.

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 clearly identifies the resource and scope: invoices the caller requested plus invoice-less payments, with full text. It implicitly distinguishes from request_invoice by referring to invoices already requested, though it does not name the sibling explicitly.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as request_invoice, get_summary, or list_requests. The content implies a retrieval use case, but no conditions or exclusions are 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=true and openWorldHint=false, so safety is covered. The description usefully adds the sort order ('newest first') and that results carry photo links, but says nothing about pagination, limits, or whether the status filter changes the result set.

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 short sentence that front-loads the scope, then ordering, then payload detail. Efficient, though its brevity is partly under-specification rather than pure concision.

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, mentioning photo links is helpful, and the read-only profile is covered by annotations. However, the undocumented status parameter and absent pagination behavior leave an agent without enough to call this correctly in filtered or large-result scenarios.

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 50%: api_key is documented in the schema, but 'status' is a bare string with no enum and no description. The description adds nothing about what values status accepts or how it filters, so the gap is not compensated.

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 conveys that this lists received mail in reverse-chronological order, and the title 'Mail that arrived' fills in the 'items' meaning that the name leaves vague. But it never uses the word mail, message, or shipment itself, so distinguishing it from siblings like list_messages or list_shipments requires 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?

There is no statement of when to use this versus list_messages, list_shipments, or get_item, and no prerequisites or exclusions. The agent must guess the routing from the name alone.

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 openWorldHint=false, so the safety profile is covered structurally. The description adds only that the messages are between the agent and the human; it says nothing about ordering, pagination, freshness, or what a message record contains.

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 a single short sentence with no wasted words and the human-channel concept is front-loaded. However, its brevity comes at the cost of not stating the core list/retrieve operation, so it is terse rather than optimally structured.

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 list tool with no output schema and an ambiguous name, the description should clarify scope, ordering, and return shape. It provides none of that, leaving the agent to infer the read behavior entirely from annotations and the sibling list.

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 single optional api_key parameter is fully documented in the schema (100% coverage), including the exact auth fallback case. The description adds no parameter semantics beyond that, so the schema is doing the work and 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 restates the resource named by the tool ('messages') but never supplies a verb such as 'list' or 'retrieve'. It adds only the channel ('between you and the human'), so an agent must infer the actual operation from the tool name.

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?

There is no guidance on when to call list_messages versus send_message, contact_human, or any other sibling. The description neither names alternatives nor states conditions for use.

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 openWorldHint=false, so safety is covered structurally. The description adds only that returned records carry a status; it says nothing about ordering, pagination, volume of results, or whether the list is filtered to the caller's account — all things annotations cannot 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?

One short sentence with no padding, which is efficient, but the brevity comes at the cost of content rather than being achieved by compression. Nothing is front-loaded beyond the possessive scope.

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?

Placeholder.

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%: api_key is documented inline but the status parameter is a bare string with no description and no enum. The description mentions 'status' only as a returned attribute, not as a filter, and gives no hint about valid values or whether it narrows the list. It therefore fails to compensate for the schema gap.

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?

"Your orders and their status" implies a listing of the caller's own order-like records, which combined with the title 'My orders' gives a rough sense of the resource. But the tool name says 'requests' while the description and title say 'orders', and it never states that this is a bulk list (versus the sibling get_request which fetches one). The verb is absent entirely.

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?

No statement of when to use this versus get_request, list_items, list_invoices, or any of the many sibling list_* tools. The only implied guidance is 'your' (scoped to the authenticated caller), with no exclusions or conditions.

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 openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that — no mention of what shipments are returned, whether results are scoped to the authenticated account, or any ordering/pagination behavior.

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

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

It is short, but the brevity comes from under-specification rather than efficiency — a single fragment that carries no actionable content. There is no front-loaded scope or filter explanation.

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 and a 50%-covered two-parameter schema, the description should explain the status filter and result scope. It does neither, leaving the agent to guess how this list tool behaves relative to the many other list_* 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 coverage is 50%; the status enum has no description and the description does not explain what each status means or that omitting it returns all statuses. The api_key parameter is documented in the schema only, so the free-text description contributes no parameter meaning.

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

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

The description 'Your announced shipments.' merely restates the tool title 'Announced shipments' without a verb or scope statement. It also sits ambiguously against the status enum (announced/arrived/cancelled), so an agent cannot tell whether this lists only announced shipments or all shipments.

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?

No guidance on when to use this versus siblings such as get_request, list_requests, or announce_shipment. The word 'announced' in the description actually conflicts with the status filter's three values, leaving the agent to infer filtering semantics.

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?

With no annotations, the description carries the full burden for a financial mutation. It lists accepted funding sources (credits, balance, x402) but says nothing about idempotency, what happens on insufficient funds, whether payment is reversible, or whether the item becomes readable after paying — a critical unknown for an agent deciding whether to invoke.

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?

Two short sentences, front-loaded with the state condition before the action. Dense and mostly waste-free, though the opening clause is slightly cryptic and requires a second read.

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-annotation, no-output-schema payment tool with half its parameters undocumented, the description leaves out too much: cost source, failure behavior, and the result of a successful payment. The essentials of calling it correctly are not fully covered.

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%; api_key is documented in the schema, but 'id' is undocumented there. The description implicitly frames 'id' as the waiting item's identifier via context, which partially compensates, but it never states the id format or confirms it refers to an item rather than a payment record.

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 (pay) and resource (item), and defines the triggering state precisely: an item that arrived without credits/balance stays 'unopened' with payment_status unpaid. This clearly separates it from sibling payment tools like pay_subscription or top_up, though it never names those alternatives explicitly.

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

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

The condition for use is implied by 'an item that ... waits unopened (payment_status unpaid) — pay it here', which is a usable trigger. However, there is no explicit when-not guidance and no routing to sibling tools (top_up for balance, buy_bundle, accept_quote) that an agent could confuse with this one.

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

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

With no annotations, the description carries the full burden, and it does disclose real behavioral facts: the per-month price, the 1–12 range, and the two payment rails (balance or x402). It does not say whether the purchase stacks onto an existing subscription, what happens on insufficient balance, or whether the call is idempotent — material gaps for a money-spending 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?

A single sentence that front-loads the action, range, and price with zero filler. Every clause carries information an agent needs before calling.

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 payment mutation with no annotations and no output schema, the definition covers cost and scope but omits success/failure behavior and any prerequisite state (registered mailbox, sufficient balance). Adequate to invoke, thin for predicting the outcome.

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 50% and the 'months' parameter has no schema description beyond min/max, so the description's '1–12 mailbox months (15 € each)' is what makes that parameter meaningful — it supplies unit and cost. The 'api_key' fallback is already fully explained in the schema, so no further detail is needed there.

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 specific verb and resource — prepaying mailbox months — with concrete bounds (1–12) and unit price (15 € each). It is clearly a spend/prepay action, distinguishable from read-oriented siblings like get_subscription or get_balance, though it never explicitly contrasts itself with pay_item or top_up.

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?

Usage is only implied: an agent can infer this is the tool for extending mailbox time. There is no explicit 'use this instead of top_up/pay_item when...' guidance, and no stated preconditions such as needing a registered mailbox or a funded balance.

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?

Only openWorldHint is annotated, so the description carries the disclosure burden and does well: it warns the API key is shown once (non-retrievable), that the HM-XXXXX code must appear on every envelope, and that an operator-less mailbox is capped at 250 €/month with letters only and no parcels. It omits whether registration itself costs money, whether the call is idempotent, and what happens on failure, 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 with the action and the return values, then the operator/address_name semantics, then the legal prerequisite. It is a dense single paragraph using 'operator_*' shorthand that is efficient but slightly harder to scan than a short bulleted breakdown; no sentence is wasted.

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 12-parameter, open-world mutation with no output schema, the description supplies the essentials an agent needs: what is created, what comes back, the operator trade-off and its limits, and the terms prerequisite. It is not fully complete — pricing/charging behavior and idempotency/error semantics are unstated.

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

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

Schema coverage is only 50%, so the description must compensate, and it targets the highest-stakes group: operator_* is framed collectively as 'the responsible human or company (the contract partner)' with the explicit trade-off for omitting it, and address_name is constrained (not a company, brand, authority or famous person). The remaining parameters (purpose, found_via, agent_model, webhook_url, open_policy) are left to schema text, so coverage of the 12-param surface is partial.

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 verb and resource plus scope: 'Create your own mailbox at a physical street address in Germany.' No sibling tool registers a mailbox, so the agent can route here without opening any schema, and the description even states what the call produces (API key shown once, HM-XXXXX mailbox code).

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 one prerequisite ('Read https://humanmailbox.com/legal/terms first') and explains the two operating modes (with vs. without operator_*), which is genuine decision guidance. But it never positions itself against siblings like start_demo, get_prices or buy_bundle — an agent cannot tell whether to try a demo, check pricing, or register directly.

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: discloses that a human performs the work, exact fees and minimums, which charges are fixed vs quoted, the quote-then-accept flow, that voucher codes land in the vault, and constraints like value_eur ≤ 100. This is exactly the economic and workflow context the 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?

Information-dense with no filler, but delivered as one telegraphic run-on paragraph of fragments ('return.', 'courier, dispose, custom.') that is hard to scan for a tool with 11 branches. Per-action line separation would cost nothing and improve selection accuracy.

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 23-param, no-output-schema dispatcher, it covers the crucial lifecycle (fixed charge now vs quoted charge awaiting accept_quote) and per-action required inputs. It never says what a successful call returns (a request id/handle to use with get_request or cancel_request), which is the main remaining 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?

With 23 params and 78% schema coverage, the description still adds the action-to-parameter mapping (text/pdf_base64 for send_letter, label_pdf_base64/address for ship_out, product/value_eur for buy_voucher, what/where/max_price_eur for buy_item, note for digitize). Undocumented elsewhere are shop, carrier, item_id, reference, shipment_id, which the description leaves unexplained.

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

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

Opens with a concrete verb+resource ('Ask the human to do something with your mail, documents or parcels') and then enumerates all 11 action values with what each does and costs. An agent can tell this is the request-dispatch tool and distinguish each action 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?

Each action value is given a use-case and price, and the closing sentence routes explicitly to the sibling 'accept_quote' for quoted parts and to balance/x402 for fixed parts. It lacks explicit when-not guidance (e.g. how it differs from announce_shipment or pay_item for pre-announced shipments), but the action-level guidance is strong.

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?

With no annotations at all, the description carries the full burden and does well: it discloses the email side effect, that the invoice is free with no VAT under § 19 UStG, that a full address is mandatory above €250, and the defaults for billing.name and email. It does not say whether repeated calls are idempotent or what happens to a payment already invoiced, which matters for a creation 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-loaded with the conditional gate before any mechanics, then packed with the invoicing scope, side effect, and billing rules in a handful of clauses. No sentence is filler.

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

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

For a nested-object creation tool with no annotations and no output schema, this covers nearly everything an agent needs: when to call, what gets picked, that an email is sent, and the address threshold. Only the return shape (invoice ID/number) and repeat-call behavior are unaddressed, which are modest gaps.

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 25% (just api_key), so the description must compensate and does: it explains payment_ids' selection semantics, the email default, the billing.name default, and the €250 full-address rule. Individual billing subfields (street, city, vat_id, country, postal_code) remain undocumented, but their names are largely self-explanatory.

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 an invoice, emails it) plus precise scope: payments that have none yet, or the given payment_ids. That scope immediately separates it from the sibling list_invoices, which only reads.

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?

'Only if you need an invoice' is an explicit when-to-use gate, and 'Nothing is invoiced unless you call this' rules out any assumption that invoicing happens automatically. It stops short of naming a specific alternative sibling or describing when-not (e.g. already-invoiced payments), so it is strong but not complete.

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?

With no annotations, the description must carry the behavioral burden; it usefully discloses a 1 € per-code charge, payment from balance or x402, and a 24-month expiry for unretrieved codes. It still omits reversibility or refund behavior, authentication details beyond the schema, failure modes, and return format.

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-load the purpose, cost/scope, and expiry. Each sentence adds necessary information with no 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?

For a paid reveal operation with no annotations and no output schema, the description covers cost, payment source, selection behavior, and expiry. It leaves return values, payment-failure behavior, and authentication details to the schema or inference.

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%: api_key is documented in the schema, while ids is not. The description compensates by explaining that ids selects specific codes and omitting it reveals all waiting codes, but it gives no id format details.

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 uses a specific verb, 'Reveal,' with the resource 'waiting codes,' and states the per-code cost. It does not explicitly contrast with sibling tools like list_codes, but 'waiting codes' and the charge make the purpose fairly distinct.

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 says 'Give ids, or nothing to reveal all waiting codes,' which clarifies call scoping but not when to choose this tool over list_codes or other code-related siblings. There are no explicit exclusions or alternative-routing instructions.

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?

With no annotations at all, the description carries the full burden, yet it omits whether the message is delivered immediately, whether it triggers human action, whether it is queued, and whether it consumes credits or has rate limits. Only the fact that it is a write to a third party is conveyed.

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 short sentence, but its brevity comes from omission rather than discipline. Every substantive detail an agent needs is absent, so there is nothing front-loaded to work with.

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 5-parameter write tool with zero annotations and no output schema, the description should explain delivery semantics, required vs optional fields, and its relationship to contact_human. None of that is present.

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 20% (only api_key is documented) across 5 parameters, and the description mentions none of them. It does not clarify the required body, nor explain what subject, item_id (presumably linking the message to an order/item), or request_id are for.

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?

"Write to the human who handles your mail" gives a verb (write) and a target (the human), so the basic intent is graspable, but it never uses the tool's own name or says this is a messaging/notification channel. Critically, the sibling set contains 'contact_human', and the description does nothing to distinguish these two tools.

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

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

There is no statement of when to use this versus alternatives, no prerequisites, and no exclusions. Given a sibling literally named contact_human, the absence of any routing guidance is a real defect for an agent choosing between them.

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?

With no annotations, the description carries the full load and does well: it discloses asynchronous behavior ('a simulated human handles your orders about 20 seconds later'), data retention (deleted after 7 days), the fact that nothing is physically shipped, and the credential return. It does not say whether repeated calls create multiple demo mailboxes or replace an existing one, which is the main remaining ambiguity.

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 compact, front-loaded description with no wasted sentences: what you get, how it behaves, what it returns, and its expiry are all stated in a single tight passage.

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

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

No output schema and no annotations, so the description must cover returns and side effects — it names api_key, the simulated-human delay, and the 7-day deletion. The only real gap is the three undocumented optional parameters, which are plausibly non-essential telemetry.

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?

Three parameters with 0% schema description coverage, and the description never mentions found_via, agent_name, or agent_model. All are optional, which limits the damage, but an agent has no idea whether these are attribution metadata it should populate or ignorable telemetry.

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 (start a demo mailbox) and immediately delimits it as a free, no-registration sandbox versus a real mailbox. The inclusion of play money, sample letter, sealed parcel and gift card code makes the scope unambiguous, and 'demo' plus 'no registration' implicitly separates it from register_mailbox.

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?

Establishes a clear context: this is the bootstrap step, since it 'Returns an api_key for all other tools'. It also flags the trial nature (deleted after 7 days, nothing shipped). It stops short of naming register_mailbox as the alternative for a persistent/real mailbox, so there is no explicit when-not clause.

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?

With no annotations, the description carries the full burden and does explain the side effect of each method: immediate USDC payment at current rate, issuance of a BTC address and amount, or a link handed to a human operator. It omits reversibility/refund behavior, the 1-1000 EUR bounds already in schema, and whether the bundle payment is deferred.

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

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

One dense sentence plus one conditional clause, front-loaded with the verb and resource, and the method list is scannable in parentheses. 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?

For a payment tool with no output schema and no annotations, the agent still lacks the response shape (address vs link vs receipt), the minimum/maximum constraints, and whether bundle and amount_eur are mutually exclusive or combinable. Adequate but with clear gaps for a money-moving operation.

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 25%, so the description must compensate, and it does: it explains what each method value means operationally and clarifies that bundle means 'buy that bundle as soon as it is paid.' Only api_key is left to the schema, which documents it adequately.

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 (add money / top up balance) and enumerates the three concrete mechanisms (x402 USDC, btc address+amount, paypal link). It is distinguishable from check_top_up and get_balance, though the closing clause about 'bundle' blurs the line with buy_bundle.

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 basis for choosing among the three methods via the parenthetical explanations, which is real routing value. However it never says when to use top_up versus check_top_up, get_balance, or buy_bundle, and never states that bundle and amount_eur are alternatives rather than stackable.

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?

With no annotations, the description carries the full behavioral burden. It does useful work by disclosing that budget_eur_month accepts null meaning 'no limit' and by spelling out the open_policy enum meanings, but it never says whether unspecified fields are left untouched (partial update) or reset, whether changes require elevated auth, or whether webhook_url is validated on 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?

One densely packed sentence with no filler, front-loading the concrete field names and their meanings. Nothing is redundant with the schema except the enum value list, which is minor.

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

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

For a 9-parameter mutation tool with no annotations, no output schema, and 11% schema coverage, the description leaves major gaps: partial-update semantics, auth requirements, side effects of setting a webhook, and the role of the purpose parameter are all unaddressed. An agent could call it but would be guessing about update behavior.

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 11%, so the description must compensate, and it partially does: budget_eur_month's null semantics and address_name's meaning are genuine additions. However, auto_reveal_codes is named with zero explanation, webhook_url gets no format or behavior detail, and purpose and api_key are not addressed at all, leaving several of nine parameters semantically thin.

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 opens with a clear verb ('Set') and enumerates the specific account fields that can be changed, so an agent knows this is a settings-mutation tool rather than a read. It never names the resource ('account') explicitly, relying on the tool name and title to carry that, and it doesn't contrast itself with siblings like get_account, but the field list makes the scope concrete.

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?

There is no statement of when to use this versus alternatives: no mention that get_account reads current values, no guidance on operator_name/operator_email versus the contact_human sibling, and no prerequisites. The agent must infer usage entirely from the field list.

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