Postly

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

Annotations already declare a non-read-only, open-world, non-destructive write, so the description's job is to add flow context — and it does: the call returns a payment link, the user must open and pay it manually, and the letter is only dispatched after payment completes. That deferred-fulfillment dependency is essential behavior an agent could not infer from annotations alone. It stops short of disclosing actual price, delivery time, or what happens if payment never occurs.

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

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

Four short sentences, front-loaded with what the tool does and immediately followed by the payment prerequisite, which is the most decision-relevant fact. No filler or repeated information; only the closing confirmation rule feels slightly appended rather than integrated.

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 mutation with no output schema and one undocumented enum, the description covers the essential contract: what is created, what is returned, and that fulfillment is payment-gated. It also documents the return artifact in lieu of an output schema. Missing details (cost, delivery timeline, letterType semantics) are secondary but non-trivial for a paid physical-mail tool.

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

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

Schema description coverage is only 40%, and the description compensates only partially: it stresses confirming the recipient address, which maps to the nested address object. It says nothing about letterType values ('almindelig' vs 'rekommanderet'), what fields sender must carry, or how text is rendered, leaving the enum and both address objects to be inferred from the schema.

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

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

States a specific verb and resource ('Opretter et fysisk tekstbrev i Danmark') plus the concrete return value ('returnerer et betalingslink'), which is more than a restatement of the name. It implicitly separates itself from the send_letter sibling by describing a deferred, payment-gated flow, but it never names that sibling, so the differentiation is behavioral 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?

'Kræver ingen API-nøgle' hints at an alternative path and 'Bekræft altid modtagerens adresse og prisen med brugeren først' gives a hard precondition, which is useful. However, it never says when to choose this over send_letter or get_pricing, and the user-confirmation rule is an operational instruction rather than when-to-use 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?

The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is carried by structured data rather than the description. The description adds only the notion that a balance and an account status are returned, with no mention of currency/units, what status values mean, or whether the call has costs or rate limits. It adds some value but stays thin beyond the annotations.

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

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

A single front-loaded sentence with no filler; the resource and its scope come first and nothing is redundant. There is no wasted wording to trim.

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 zero-parameter read-only tool with no output schema, the description covers purpose and the shape of the return (balance + account status) adequately. A small gap remains around units/currency and the meaning of the status field, which the agent cannot get from structured data.

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 and the baseline of 4 applies. Nothing misleading is said about inputs.

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

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

The description pairs a specific verb ("Viser" / shows) with a specific resource and scope: the prepaid balance and account status for the associated API customer. An agent immediately knows what data comes back. It does not, however, distinguish itself from siblings such as get_pricing, which could plausibly be confused with balance/account information.

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 prerequisites, and no named alternative. Usage is only implied by the purpose (check remaining credit / account state), leaving the agent to infer that this should be called before placing orders such as create_letter_order or send_letter.

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 the useful scoping fact that the letter must have been previously sent, but says nothing about what the returned status comprises, whether results are cached/live, or what happens when the id is unknown.

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 well-formed sentence with the scope constraint front-loaded before the lookup key. Nothing is redundant or padded.

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

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

For a one-parameter read tool this is close to adequate, and annotations cover the safety profile. However, with no output schema the description should have sketched what the status response contains (e.g. delivery state, timestamps) and what an invalid or unknown id yields; that information is absent.

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

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

The schema has 0% description coverage for the single required `id` field, so the description must carry the meaning. It only says "ud fra dets id" (based on its id), which identifies the id as the letter's own identifier rather than an order id, but adds no format, source, or example. This is thin compensation 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 description pairs a specific verb with a specific resource: "Viser status for et tidligere sendt brev" (shows status for a previously sent letter). The qualifier "tidligere sendt" separates it from send_letter and list_letters, but no sibling is named explicitly, so differentiation is only partial.

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 "tidligere sendt brev" implies a precondition (the letter must already have been sent) and thus steers agents away from using it for unsent orders, but this is inferred rather than stated. There is no explicit when-not guidance and no mention of get_order_status or list_letters as alternatives for other lookup 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 useful context by naming example status values ('betalt eller afsendt'), but says nothing about auth requirements (the 'uden API-nøgle' note lives only in the title), rate limits, or whether statuses are eventually consistent.

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 padding; the purpose lands in the first three words. It could have used one more short clause on the return shape without becoming 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?

This is a one-parameter read-only lookup with annotations covering the safety profile and no output schema to explain. Given that simplicity, the description plus the create_letter_order link gives the agent enough to invoke it correctly; the remaining gaps are marginal.

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

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

Schema description coverage is 0% for the single orderId parameter, so the description must carry the meaning. It partially compensates by tying the id back to create_letter_order, implying orderId is the identifier returned by that call, but it never states the format or where to obtain it explicitly.

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

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

The description states a specific verb and resource ('Viser status for en ordre') and anchors it to the sibling that creates such orders ('oprettet med create_letter_order'). It stops short of distinguishing itself from get_letter_status, which is the closest-sounding sibling, so the agent must infer the order-vs-letter scope split.

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: the reference to create_letter_order suggests this is the follow-up call after placing an order. There is no explicit when-to-use statement, no exclusion of get_letter_status, and no mention of whether the order must be freshly created or can be queried at any time.

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

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

The readOnlyHint and openWorldHint annotations already establish that this is a safe, self-contained read against Postlys's own data. The description adds that prices are 'aktuelle' (current) and covers two letter classes, which is modest extra context. It says nothing about currency, whether prices include VAT, caching/freshness guarantees, or rate limits.

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 with no filler, and the resource and its scope are front-loaded. Nothing in it is redundant with the title beyond unavoidable overlap.

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 zero-parameter tool this is nearly sufficient, but with no output schema the description should say something about the shape of the return value — a price list per letter type, currency, or validity period. As written, an agent knows what the tool fetches but not what it receives back.

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 the baseline of 4 applies; there is nothing for the description to disambiguate. The mention of two letter categories ('almindelige og rekommanderede') is informative about coverage but is not mapped to any input, since none exist.

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

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

The description states a specific verb and resource ('Henter ... aktuelle priser') plus the scope of what is priced ('almindelige og rekommanderede breve'). This clearly separates it from the sibling tools, which all deal with orders, letters, or balance rather than prices. It stops short of naming a sibling outright, but no ambiguity remains.

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 price-lookup step before calling create_letter_order or send_letter, since every sibling is order- or letter-oriented. There is no explicit statement of when to call it, no prerequisites, and no mention of alternatives or when not to use 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 that results are scoped to the calling account and limited to recent items, but says nothing about ordering, default page size, or whether further results can be fetched.

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, front-loaded sentence with no filler. Its brevity is efficient, though the same terseness is what leaves usage and parameter gaps unaddressed.

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

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

For a two-optional-parameter read tool with annotations covering safety and no output schema to explain, the description is minimally adequate. It is still thin on result ordering, default limit, and how this differs from the single-letter status tools.

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 the "reference" parameter carries a schema description, leaving "limit" (1-50) undocumented in both places. The description never mentions either parameter or explains that limit caps how many recent letters are returned, so it fails to compensate for the 50% 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 description gives a specific verb ("Lister") plus resource ("breve") and a clear scope ("seneste breve sendt af denne konto"), so an agent knows it retrieves a recent-sent list rather than a single letter. It does not name or contrast with siblings like get_letter_status or get_order_status, which is why it stops short of a 5.

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

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

There is no when-to-use guidance, no exclusions, and no mention of alternatives among the six sibling tools. The agent must infer from the phrase "seneste breve" alone that this is the bulk-list tool versus the single-item status tools.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description adds two operationally important facts an agent would otherwise not know: the cost is debited from the prepaid balance, and the letter is irreversible once dispatched. It stops short of covering the test-key behavior, idempotency expectations, or what happens on insufficient balance.

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 the core action front-loaded and the cost/irreversibility caveats immediately after. No filler, though the very short text leaves obvious room for routing and parameter hints that would earn their place.

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

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

The description is incomplete relative to a nine-parameter financial, irreversible mutation with no output schema and no annotation coverage of cost or reversibility. It says nothing about return values, success/failure shape, or the address and file parameters, so an agent could not confidently construct a correct call from it.

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 56% and the description adds nothing about any of the nine parameters — no mention of letterType (almindelig vs rekommanderet), the sender/recipient address objects, text vs fileBase64 exclusivity, or the role of idempotencyKey. The description does not compensate for the undocumented half of the schema.

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

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

The description opens with a concrete verb and resource: "Sender et fysisk brev i Danmark" (send a physical letter in Denmark). It is clear what the tool does, but it never names or contrasts with the closest sibling, create_letter_order, so the agent must infer the distinction from names alone.

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 or when-not-to-use guidance, and no mention of alternatives such as create_letter_order (order-based flow) or get_pricing/get_balance. The prepaid-balance and non-cancellable statements describe consequences of calling, not conditions for choosing this tool.

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