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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is fully covered. The description adds one genuinely useful behavioral detail not in structured data — that amounts are in minor units — but says nothing about error cases, auth requirements, or lookup failure 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?

A single front-loaded sentence with no filler, and the minor-units caveat is tucked in a parenthetical rather than buried. It is lean to the point of being terse for a tool with an undocumented required parameter.

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 complete annotations and no output schema, the description covers the essentials (what is fetched, by which key, unit convention). It does not describe the returned capture's shape or error behavior, and one required parameter is undocumented anywhere.

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%: order_id is documented as a UUID (not merchant number) while capture_id has no schema description at all. The description only restates that lookup is by capture_id and that the order is a Klarna order, adding no format or constraint detail for the undocumented parameter.

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 (Get), resource (capture), and the key used to fetch it (capture_id) plus the owning entity (Klarna order). The singular 'one capture' implicitly contrasts with the sibling list_captures, but no sibling is named explicitly, so it stops short of full 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?

The description gives no when-to-use or when-not-to-use guidance and never names alternatives like list_captures or get_order. An agent must infer that this is the right tool only when it already holds a capture_id.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description earns credit by disclosing payload scope (requests, deadlines, evidence history) and freshness ("current state"), which matters because there is no output schema — though it omits auth or identifier-validity notes.

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 core action leads and the returned content follows. Every clause contributes.

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 single-item read with a full safety annotation set and no output schema, the description covers what is returned and the resources involved. The only notable gap is the absence of any identifier provenance or error 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 0% and the single required parameter payment_dispute_id gets no explanation of format, source, or constraints. "One dispute" only weakly implies that an identifier must be supplied; the description adds essentially no meaning beyond the schema's property name and maxLength.

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

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

The description gives a specific verb and resource ("Get one dispute") and scopes the result to current state plus requests, deadlines and evidence history. A sibling list_disputes exists, and the singular "one dispute" implies retrieval by identifier versus listing, though the sibling is not named 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?

Usage is only implied: you fetch a single dispute when you have an identifier and need its detail. There is no explicit when-to-use statement, no prerequisites, and no pointer to list_disputes for discovery versus this tool for detail.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuine context beyond them: the status enumeration (including terminal states like CANCELLED/EXPIRED/CLOSED) and the minor-units convention, which materially affects how an agent interprets returned amounts.

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, front-loaded with the verb and resource before the field inventory. The long mid-sentence field enumeration is dense and arguably longer than needed, but every item listed is return-value information an agent would otherwise have to probe for.

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 does so by naming the key fields and the amounts convention. What remains unstated are error/not-found behavior and whether nested lists (captures, refunds) are paginated or truncated.

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 order_id parameter is already documented in the schema, including the UUID format and the 'not the merchant order number' caveat. The description adds no further parameter meaning, 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?

Opens with a specific verb+resource ('Get a Klarna order') and immediately enumerates the data surfaced: status, amounts, order lines, captures, refunds, merchant references, addresses. It also pre-empts confusion with a sibling by explaining that refunds are listed here because there is no separate list-refunds endpoint.

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 closing sentence gives concrete routing guidance: use this tool to see refunds for an order since Klarna exposes no separate list-refunds endpoint, which steers the agent away from hunting for a dedicated sibling. It stops short of explicit when-not-to-use conditions (e.g. expired or not-found orders) or pointing at list_captures / get_payment_session as complements.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds genuine scope context beyond that: the enumerated session contents (including expiry) and the flat statement that 'this server never creates or updates sessions,' which prevents an agent from attempting mutation calls. It omits auth needs, rate limits, and behavior for expired/unknown session IDs.

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, front-loaded with the verb, resource, and lookup key before the returned fields and use case. The closing 'This server never creates or updates sessions' largely restates readOnlyHint and is the one clause that doesn't fully earn its place, but overall there is no filler.

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

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

For a one-parameter read tool with no output schema, the description usefully enumerates what comes back, so the agent knows what it can inspect without a response schema. The remaining gaps are minor: session_id format/derivation and the outcome when a session has expired or does not exist.

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

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

Schema description coverage is 0%, so the description must compensate for a single required string parameter, and it only restates the identifier ('by session_id') without format, origin, or where to obtain the value. It confirms which entity the ID identifies (a Klarna Payments session), which is marginally useful, but adds little semantic detail beyond the property name.

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 (read) and resource (Klarna Payments session) keyed by session_id, then enumerates the payload surface: status, order amount and lines, country/currency, payment method categories, expiry. This is plainly distinct from the sibling set (disputes, orders, captures, payouts, transactions), so an agent can route without opening a schema.

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

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

Gives a concrete trigger scenario: 'Useful when debugging a checkout that never became an order,' which tells the agent this is a pre-order artifact lookup. It does not name an explicit alternative (e.g., use get_order once a purchase order exists) or state when-not-to-use, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral detail beyond them — totals are in minor units — but says nothing about error behavior when the reference is unknown or about the response shape.

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, no filler, with the core action front-loaded and the identifier and unit convention appended as useful qualifiers. Nothing could be cut without losing meaning.

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

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

For a single-parameter read tool with no output schema, the description covers the identifier source and the currency-unit convention, which is the main non-obvious detail an agent needs. It stops short of describing what a returned payout contains, but the essentials are 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 100% for the single parameter, so the schema already explains payment_reference, including that it appears on the bank statement or in list_payouts. The description's parenthetical largely restates that, adding only slight reinforcement, so the baseline of 3 applies.

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

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

States a specific verb and resource (get one Klarna payout), names the identifying key (payment_reference), and scopes it against the sibling list_payouts / get_payout_summary by making clear it retrieves a single payout. An agent can select it without opening the schema.

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

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

Usage is implied by the requirement of a bank-statement reference and the singular 'one payout', which distinguishes it from the list/summary siblings. However, there is no explicit when-to-use or when-not-to-use statement, and no sibling is named as an alternative.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so safety is covered. The description usefully adds the return format (CSV text), the payload scope (all transactions for one payout), and the format provenance (Klarna's documented settlement report format). Pagination, size limits, or error behavior for an unknown payout are not disclosed.

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 in what format before the usage hint. Minimal waste; the parenthetical format note is small but justified.

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 one-parameter read tool with no output schema, the description covers the return format and content, which is what an agent most needs. The remaining gap is the meaning/source of payment_reference and behavior on invalid references.

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 required parameter payment_reference, and the description only says 'for one payout' without clarifying whether that reference is the payout ID or a payment reference. An agent cannot tell from the definition what identifier value to supply or where to obtain it.

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

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

States a specific verb (download), resource (settlement report for one payout, including its transactions) and output format (CSV text). The singular 'one payout' implicitly contrasts with the plural sibling get_payouts_summary_report_csv, but no sibling is named 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?

'Use for reconciliation in a spreadsheet' gives a concrete usage context that separates it from the JSON get_payout/get_payout_summary tools. It does not, however, state exclusions or name a direct alternative (e.g., get_payouts_summary_report_csv for multiple payouts).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds genuinely useful non-annotation context: the output can be large and the date range should be kept to a month or less, which warns the agent about payload size. It stops short of stating whether results are truncated or what the CSV 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?

Two short sentences with no filler. The purpose is front-loaded and the operational caveat follows immediately; every clause carries information.

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

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

With no output schema, the description correctly names the return format (CSV) and warns about size, covering the essentials for a two-parameter report tool. It omits how the CSV is delivered (inline text, URL, or file reference), which is a minor gap for a download-style tool.

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

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

Schema description coverage is 100%: both start_date and end_date document ISO 8601 format, examples, and bare-date semantics. The description only restates that there are two dates and adds no format or boundary detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (download) and resource (CSV report of payouts and their transactions) with the scope bounded by two dates. However, it does not distinguish itself from the near-identical sibling get_payout_report_csv (nor from get_payout_summary), so an agent cannot tell which report tool to pick without further inspection.

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 date-range framing implies usage context, and the size caveat hints at when this is appropriate, but there is no explicit when-to-use guidance and no alternative named for cases where a JSON, paginated listing (e.g. list_payouts) would be preferable. Guidance is implied rather than 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral detail beyond them: one entry per currency, the exact aggregate fields returned, and that amounts are in minor units. It omits granularity/auth/pagination details but adds meaningful context.

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

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

Front-loaded with the core purpose in one dense sentence, then a short usage hint. The field enumeration is long but each term earns its place for a financial summary; no filler sentences.

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 well by listing every aggregate field and the unit (minor units) plus the per-currency granularity. It could still note whether currency_code narrows the result, but it is otherwise sufficient.

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 start_date/end_date format and the currency_code pattern are already fully documented in the schema. The description only echoes the date-range scoping and never mentions currency_code filtering, so baseline 3 is appropriate.

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

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

States a specific verb+resource (summary of payouts) and enumerates exactly what each entry contains, which cleanly separates it from the per-payout siblings list_payouts/get_payout. It does not name a sibling explicitly, so 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?

"Good for monthly reconciliation" implies a usage context but gives no explicit when-to-use/when-not guidance and never names the competing aggregate tools (get_payout_report_csv, get_payouts_summary_report_csv) to route 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the exact return payload (refunded_amount, time, description, reference, order lines) with the unit caveat 'minor units', which matters because there is no output schema.

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

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

Two sentences, front-loaded with the action and key, followed by the alternative. The field enumeration is dense but earns its place since no output schema exists; the sentence is slightly overloaded with a colon-delimited list.

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 compensates well for the missing output schema by listing the refund fields returned, and annotations cover the read-only/idempotent profile. The remaining gap is the undocumented refund_id format and any error/not-found behavior, though these are minor for a simple point-lookup 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 50% — order_id is documented as a Klarna UUID that is explicitly not the merchant order number, while refund_id has no schema description at all. The description only restates that lookup is 'by refund_id' and does not give its format or clarify how it relates to order_id, so the schema plus description together still leave the second parameter under-specified.

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 precise verb+resource pair ('Get one refund on a Klarna order by refund_id') and enumerates the returned fields, so the agent knows exactly what entity it fetches and by which key. It also explicitly distinguishes itself from the listing path by naming get_order, so no sibling schema needs to be opened to disambiguate.

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

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

It gives a clear use context (retrieve a single refund by refund_id) and names the alternative tool for the listing case (get_order). It stops short of stating exclusions or prerequisites, such as whether the refund must already be settled or whether it requires the order to be fetched first, but the when-to-use routing is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds useful field-level context (captured_amount/refunded_amount in minor units, capture time, references, shipping info) but says nothing about pagination, result counts, or external-system behavior implied by openWorldHint.

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 tightly packed sentence with the resource and scope front-loaded and zero filler. Every clause (verb, target, returned fields) 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?

For a read-only list tool, annotations cover safety and the schema fully covers the sole parameter; with no output schema, the description usefully enumerates return fields. The only shortfall is absent pagination/ordering guidance for a list endpoint.

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

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

Schema description coverage is 100%, and the single order_id parameter is fully documented in the schema (UUID, not the merchant order number). The description contributes no additional parameter syntax or format detail, 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 uses a specific verb and resource ('List all captures on a Klarna order') and even enumerates the returned fields, so an agent knows exactly what it does. However, it never distinguishes itself from the close sibling 'get_capture' (singular), leaving the agent to infer the difference.

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 when-to-use or when-not-to-use guidance is provided, and no alternative tool is named. The phrase 'on a Klarna order' implies the context, but the agent receives no explicit routing advice versus get_capture or the other list_* siblings.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds non-obvious behavior the annotations cannot express: the enrollment prerequisite and the important ambiguity that an empty list may mean the account is not enrolled, which prevents a false 'no disputes' conclusion.

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 dense sentences, front-loaded with the verb/resource and filter axes before moving to domain states, pagination mechanics and the enrollment caveat. Little padding, though the state enumeration slightly duplicates the schema enum.

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 15-parameter, no-output-schema listing tool with annotations already covering safety, the description supplies the crucial extras an agent needs: pagination protocol, enrollment precondition and the empty-result caveat. The remaining gap is that several filter parameters (merchant_ids, payment_transaction_ids) are not characterized anywhere.

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 15 parameters, so the description must carry weight. It does add meaning for cursor usage (pass pagination.last_item as starting_after) and enumerates the valid state values, but it omits explanation of merchant_ids, order_ids, payment_transaction_ids, size, sort_by and the four date-range boundaries, leaving nearly half the surface undocumented in both places.

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

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

States a specific verb (List) plus resource (customer disputes) and enumerates the filter axes (order, state, reason, purchase reference, date ranges), so the agent immediately knows this is the multi-item search endpoint. It does not name get_dispute as the singular alternative, so differentiation from the sibling is left to inference rather than stated.

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 real operational context: the merchant account must be enrolled for the Disputes API, and an empty result can indicate non-enrollment rather than zero disputes. It also explains the cursor flow. It stops short of an explicit when-to-use-this-vs-get_dispute rule, but the list/fetch distinction is implied by the pagination guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false and openWorldHint, so the safety profile is covered. The description then adds real behavioral context: amounts are in minor units, the response includes a pagination object with total, and each payout carries a defined set of total fields. That is meaningful disclosure beyond the structured data, though it says nothing about rate limits or default page size 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?

Two dense sentences with no filler: the resource definition and returned totals come first, then filtering and pagination. Every clause carries information and nothing is repeated from the schema verbatim.

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

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

With no output schema, the description compensates by naming the per-payout total fields, stating units (minor units), and describing the pagination envelope with total. An agent can call and interpret it correctly. Missing only edge behavior such as default page size or empty-result handling.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters with ranges, formats and defaults. The description only restates that filtering is by payout date range and currency and that size/offset drive pagination, adding the useful nuance that the date filter is on payout date rather than creation date, but no syntax beyond the schema. Baseline 3 is appropriate.

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

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

Names a specific verb (List) and resource (Klarna payouts), and defines the resource parenthetically as settlements to your bank account, which removes ambiguity. It also enumerates the per-payout totals returned. It does not explicitly distinguish itself from close siblings like get_payout_summary or list_payouts_summary_report_csv, so 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?

States that results can be filtered by payout date range and currency and are paginated via size/offset, which implies the intended usage pattern. However, it gives no explicit when-to-use or when-not-to-use guidance, nor does it name the alternative tools (get_payout, get_payout_summary, the CSV report siblings) an agent should pick instead in other situations.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the bar is lower. The description adds real context beyond them: the absence of a date filter in Klarna's API, the minor-units amount convention, and pagination via size/offset. It stops short of auth or rate-limit details, but the disclosed API constraint is the important behavioral fact.

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 dense sentences, front-loaded with purpose and returned fields, then filters, then the workaround for date ranges, then pagination. No filler and nothing repeated from the schema.

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

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

With no output schema, the description compensates by naming the returned fields (amount in minor units, order id, capture/refund ids, merchant references, payout reference) and covers filtering and pagination. An agent has everything needed to call it correctly, including the cross-tool workflow for time-bounded queries.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by explaining that payment_reference is a payout reference (obtained from list_payouts) and that the two filters can be combined ('and/or'), which is semantic linkage the schema's field descriptions do not convey.

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

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

States a specific verb (List) and resource (settlement transactions), enumerates the transaction types (SALE, RETURN, FEE, REVERSAL) and the fields returned, and is clearly distinguishable from siblings like list_payouts and list_disputes.

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

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

Gives explicit filter conditions (by payout payment_reference and/or order_id) and, crucially, routes the agent to the sibling tool for date-range queries: 'find the payouts with list_payouts and pass each payment_reference', because the API has no date filter. This is exactly when-to-use/when-not guidance.

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