checkoutcom

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

Annotations only supply destructiveHint=true; the description adds substantive context beyond that: that the operation moves money, that it settles an authorized amount, that partial captures are supported, and the underlying endpoint (POST /payments/{id}/captures). It does not discuss reversibility or failure/idempotency behavior, but the money-movement warning is genuinely valuable.

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 tight sentence with the highest-stakes fact (moves money) front-loaded via emphasis, followed by the endpoint. Zero filler.

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

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

For a five-parameter mutation with no output schema, the description conveys the critical facts: it is a settlement operation on a prior authorization with partial support. It omits any note on reversibility or what the capture response yields, but the schema covers all inputs and no output schema exists to explain.

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 id, amount, metadata, reference, and idempotency_key are already documented in the schema. The description only echoes the full-vs-partial amount concept, adding no syntax or format detail beyond what the schema provides. Baseline 3 applies.

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

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

States a specific verb (CAPTURES) and resource (previously authorized payment) with the exact effect spelled out: it settles the full or partial authorized amount. This clearly separates it from sibling mutators like checkout_void_payment and checkout_refund_payment without needing to open 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?

The phrase 'previously authorized payment' implies the precondition for use, which is useful. However, it names no alternatives and gives no when-not guidance — an agent must infer on its own why it would capture rather than void or refund. Implied usage only.

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 carry the mutation signal via destructiveHint=true, so the bar is lower. The description usefully notes the endpoint (POST /customers) and that instruments and payments can later attach to the record, but it omits idempotency behavior, the uniqueness constraint's consequences, and any error/auth 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?

Three terse sentences, front-loaded with the action and with zero padding. The endpoint reference adds value rather than noise.

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 exists, so the description would ideally indicate what a create returns (e.g. the generated customer id), but it does not. It covers what the tool is and its side effect reasonably well for a create operation, leaving the return shape unspecified.

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 all six parameters are already documented in the schema. The description adds nothing beyond the schema for parameters, 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 and resource ('CREATES a customer record') and adds useful scope in the parenthetical about what can be attached to it. Distinguishing it from the get_customer sibling is easy from the verb alone, though the description never names or contrasts a 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?

No when-to-use guidance, no prerequisites, and no alternatives named. 'This ADDS data to your account' hints at the mutation intent but does not tell an agent when to choose this over e.g. checkout_create_payment.

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 only annotation is destructiveHint=true, so the description carries most of the behavioral burden. It adds critical context that this moves money, charges a card, and can authorize or immediately capture, plus the POST /payments endpoint. It does not cover idempotency behavior, permission requirements, 3DS/authentication handling, or return behavior, so it stops short of exhaustive.

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

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

The description is front-loaded with the critical action and money-movement warning, then gives the endpoint and required inputs. Every sentence earns its place with no filler.

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

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

For a destructive 11-parameter payment-creation tool, the description covers the core behavior and required invocation fields, while the schema documents the optional parameters. It omits return-value expectations and idempotency guidance, but remains sufficient to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters. The description repeats the three required parameters and source-object examples, but adds no syntax, constraints, or meaning beyond what the schema provides.

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 and resource: creates a payment and explicitly states it moves money by charging a card/payment source. It also distinguishes authorization from immediate capture and names the Checkout.com endpoint, so an agent can identify it as the charge-creation tool rather than a capture, refund, or void tool.

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 clear implied usage: use this when charging a payment source to create an authorization or capture. However, it does not explicitly say when to use this instead of siblings such as checkout_capture_payment, checkout_create_payment_link, or checkout_refund_payment, and it states no prerequisites or exclusions.

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

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

Annotations only carry title and destructiveHint=true, so the description must shoulder most of the behavioral load. It usefully discloses the side effect (creates a payable link) and the return value (a URL), but says nothing about idempotency handling, expiry semantics, or permissions.

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, front-loaded sentences that lead with the action and the outcome. The capitalized emphasis is slightly noisy but 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 creation tool with 11 mostly-optional parameters, full schema documentation, and no output schema, the description covers the essential outcome (hosted link plus URL). Remaining gaps (idempotency, auth, expiry) are minor given the rich schema.

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

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

Schema description coverage is 100% across all 11 parameters, including nuances like minor units for amount, so the schema already does the heavy lifting. The description adds no parameter-level detail beyond that, making the baseline 3 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 and resource ('CREATES a hosted Payment Link'), clarifies the financial intent ('COLLECT MONEY'), and names the backing endpoint (POST /payment-links). It separates itself from checkout_create_payment by emphasizing the hosted, shareable link, though it does not name siblings 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 implied by 'Returns a URL to share with the customer', which suggests the send-a-link scenario, but there is no explicit when-to-use versus checkout_create_payment or other collection siblings, and no preconditions (auth, idempotency) 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?

With readOnlyHint=true already declaring this is a safe read, the description's added value is limited to the returned field list and the REST endpoint. It says nothing about not-found behavior, rate limits, or auth requirements, so a 3 is appropriate.

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 purpose then the lookup mechanics; no filler and 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?

For a read-only single-parameter getter with no output schema, the description usefully enumerates the returned fields and names the endpoint. Minor gap: no mention of error/not-found behavior, but nothing essential to calling it is missing.

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

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

Schema coverage is 100% and the single 'id' parameter is fully documented in the schema, including that it accepts 'cus_...' or an email. The description merely repeats that, adding no syntax or format detail beyond the schema.

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

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

States a specific verb+resource ('Get a customer's details') and enumerates the fields returned (email, name, phone, saved instruments), plus the lookup key formats. It is clearly distinguishable from the sibling checkout_create_customer.

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?

Explains the two ways to identify the customer ('cus_...' id or email) and cites the underlying endpoint, giving clear context for invocation. It does not state any when-not conditions or explicitly name an alternative tool, so it stops 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?

The readOnlyHint annotation already establishes this is a safe read, so the description's real contribution is disclosing the response contents (reason code, amount, deadline, evidence status), which matters because there is no output schema. It still says nothing about not-found behavior, permissions, or any rate/size 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?

Two compact sentences: the operation and its payload first, the raw endpoint second. Nothing is wasted and the most useful information leads.

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, no-output-schema read tool this covers what an agent needs: the operation, the id format, and the shape of the returned data. Adding error/not-found behavior would make it fully complete, but nothing essential is missing.

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

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

Schema description coverage is 100% and the single id parameter is documented with its 'dsp_...' format in the schema. The description only repeats that format, adding no new semantics beyond what the schema already provides — the baseline for full coverage.

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

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

States a specific verb+resource (get a single dispute) and even enumerates the returned fields (reason code, amount, deadline, evidence status), which separates it in spirit from checkout_list_disputes. It never names that sibling explicitly, so the differentiation is implied by 'single ... by id' 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?

Usage is implied by the 'by id dsp_...' framing, but there is no explicit when-to-use, no exclusion, and no pointer to checkout_list_disputes for the browse case. An agent can infer the intent but is given no 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?

The readOnlyHint annotation already communicates that this is a safe read-only operation. The description adds useful context that the rates are 'indicative' and tied to Checkout.com's processes, but does not cover auth needs, rate limits, or response behavior beyond what annotations provide.

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 concise sentences, front-loaded with the tool's purpose, followed by a direct API endpoint reference. Every element earns its place 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 read-only tool with full input schema coverage and annotations, the description is largely complete. The lack of an output schema means an agent might benefit from a note on return format, but the description does not need to explain return values here.

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 all four parameters are fully documented in the input schema. The description adds no additional parameter meaning, which matches the baseline of 3 when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Get the indicative foreign-exchange rates Checkout.com uses') with clear scope and an example use case. No sibling tool deals with forex rates, so it is easily distinguishable from the payment/customer/dispute 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?

Usage is implied by the example '(e.g. for card payouts)', but there is no explicit guidance on when to use this tool versus alternatives or when not to use it. The unique nature of the resource makes the gap minor.

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, so the safety profile is covered. The description restates that this is a GET and names the endpoint, but adds no auth requirements, rate limits, error behavior, or return shape beyond what annotations and the name already convey.

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

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

Two compact sentences with the core purpose front-loaded. The endpoint notation is arguably redundant but costs little and keeps the definition efficient.

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 retrieval with a readOnly annotation, the description identifies the resource and id format adequately. Without an output schema, it could specify more about the returned instrument details, but it is sufficient for a basic get 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 description coverage is 100%, and the single id parameter is fully documented in the schema with the same 'src_...' example. The description repeats that format but adds no new parameter meaning, 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?

The description states a specific verb (Get), resource (saved payment instrument), and identifier format ('src_...'). It is distinguishable from siblings because no other tool targets instruments, though it does not explicitly name alternatives for 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 provides no when-to-use guidance, prerequisites, or alternatives. It only implies usage when an instrument id is available, which is minimal context rather than explicit 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?

readOnlyHint=true already declares this as a safe read, so the description's burden is light. It usefully clarifies that both 'pay_' and 'sid_' identifiers are acceptable and maps to the concrete REST endpoint, but says nothing about error behavior (e.g. not-found handling) or what the 'full details' payload 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 tight sentences, front-loaded with the core action and followed by the identifier format and endpoint mapping. Nothing is padded and no sentence is redundant.

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 a readOnlyHint, the essential facts (what it fetches, by what id, against which endpoint) are present. The absence of an output schema means the shape of the returned payment details is unspecified, a minor gap the description does not attempt to close.

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% with a single well-documented id parameter, so the schema already carries the semantics. The description's example prefix ('pay_...') and session-id note largely restate the schema, meeting the baseline of 3 without adding new syntax or format rules.

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

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

States a specific verb+resource (get the full details of a payment) and clarifies it also accepts a payment session id, with the underlying endpoint GET /payments/{id}. It distinguishes itself implicitly from list/search siblings by being an id-based single-record fetch, though it never names those alternatives.

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: you call this when you already have a payment id. There is no explicit guidance on when to prefer this over checkout_search_payments, checkout_get_payment_actions, or checkout_list_payments, and no stated preconditions or exclusions.

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, so the safety profile is covered by structured data. The description adds one genuine behavioral trait beyond annotations: the ordering guarantee ('latest first'), which tells the agent how to interpret the result sequence. It does not disclose pagination behavior or result volume, so it stops short of a 4.

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, no waste, front-loaded with the verb and resource before the endpoint reference. Every clause 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?

With no output schema, the description does double duty by naming the action types returned plus the ordering, which is enough for an agent to call and interpret it. It could still mention pagination or whether the list can be empty on an unprocessed payment, so it is strong but not exhaustive.

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

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

Only one parameter, and schema description coverage is 100% ('Payment id, e.g. pay_...'), so the schema fully documents the input. The description adds nothing about the id format or scope beyond what the schema already provides, making the baseline 3 correct.

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 ('actions ... associated with a payment') and enumerates the action kinds returned (authorization, capture, refund, void). This clearly separates it from the sibling checkout_get_payment, which retrieves the payment itself rather than its action history.

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 resource description but there is no explicit when-to-use guidance or routing versus alternatives such as checkout_get_payment or checkout_list_payments. An agent must infer that this is the audit-trail companion to the payment detail call.

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, so the safe-read nature is covered structurally. The description adds the underlying REST mapping (GET /payment-links/{id}), which is useful context, but says nothing about error behavior (e.g. not-found) or return shape. With annotations carrying the safety profile, this is adequate but not rich.

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 front-loaded sentence containing the action, the resource, the identifier, and the endpoint mapping. 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?

This is a simple one-parameter read tool with annotations and no output schema; the description covers what is fetched (details and status). It is complete enough to call correctly, though it could note error cases or confirm the id format contract.

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 parameter is fully documented with an example format there. The description repeats the 'pl_...' id format, adding mild reinforcement but no new syntax or constraints beyond the schema.

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

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

States a specific verb ("Retrieve") and resource ("Payment Link") plus the scope of what is returned ("details and status"). It is distinguishable from the create/list siblings, though it does not name or explicitly contrast with them.

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 implies usage by requiring an id, so an agent knows this is a single-record lookup. However, there is no explicit when-to-use guidance, no prerequisites (e.g. payment link must exist), and no mention of alternatives such as get_payment or list operations.

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 readOnlyHint=true already declared, the safety profile is covered by annotations; the description adds genuinely useful context that the response is metadata plus references to downloadable files, which matters given there is no output schema. The 'GET /reports/{id}' restatement of the endpoint adds little on its own.

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 compact sentences, no filler, with the resource and the id format front-loaded. 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?

For a simple one-param read tool with annotations covering safety, the description supplies the one thing structured data does not: what the payload contains (metadata and downloadable files). It could say slightly more about the report object, but it is essentially 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?

There is a single parameter at 100% schema description coverage, so the schema already documents the 'rpt_...' format. The description repeats the same prefix convention, adding no syntax or constraint information beyond the schema.

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

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

The description states a specific verb (Get) and resource (metadata of a specific report) and scopes it to retrieval by id, which clearly separates it from the sibling checkout_list_reports. It does not name the sibling explicitly, but the by-id vs. list distinction 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?

Usage is implied: call it when you already have an 'rpt_...' id. There is no explicit when-to-use guidance, no statement of prerequisites (e.g. that the id must come from list_reports), and no named alternatives.

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 annotation already declares this is a safe read. The description adds genuinely useful behavior beyond that: the default sort order by last-modified. However it says nothing about pagination semantics, result-size behavior, or rate limits, so it is a modest addition rather than rich disclosure.

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 scope and ordering front-loaded before the trailing 'Checkout.com: GET /disputes.' The endpoint reference is marginally useful rather than essential, but nothing is bloated or buried.

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 eight optional parameters, no output schema, and only a readOnlyHint annotation, the description does not convey what a returned dispute record contains, how large result sets behave, or when pagination via skip/limit becomes necessary. It is adequate to select the tool but incomplete for confident invocation.

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

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

Schema description coverage is 100%, so every parameter is already documented with format, bounds, and defaults in the schema. The description only alludes to 'optional filters' generically and adds no syntax, combination rules, or format detail beyond what the schema provides.

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 (disputes), clarifies the domain synonym (chargebacks), and pins down the ordering (most-recently-modified first) plus the presence of optional filters. An agent can immediately separate it from the singular checkout_get_dispute sibling.

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 'optional filters' and by the fact that this is the collection endpoint, but there is no explicit when-to-use guidance, no direction on which filters matter for which scenario, and no stated alternative (e.g. use checkout_get_dispute when you already have an 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's duty is reduced. It adds only the underlying REST call (GET /payments, query parameters) and nothing about result volume, retention, or whether pagination is required to see everything. Adequate but thin beyond the annotation.

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: purpose, then routing, then API trivia. The three short sentences contain little waste, though 'Checkout.com: GET /payments (query parameters)' is implementation detail that contributes marginally to tool selection.

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 3-parameter read tool with full schema coverage and a readOnly annotation, the description covers purpose, the filter, pagination fields via schema, and the richer alternative. No output schema exists, so return-shape omission is acceptable; only the no-reference default is 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 description coverage is 100%, so skip, limit and reference are already fully documented in the schema. The phrase 'match a given reference' only echoes the reference property, adding no format, matching mode, or partial-match semantics. Baseline 3 applies.

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

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

States a specific verb (List) + resource (payments) + scope (matching a given reference) in one clause. It also names the sibling it is not, so an agent can distinguish it from checkout_search_payments without opening either schema.

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

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

Explicitly routes the agent to checkout_search_payments 'for richer filtering', which is a clear when-to-use signal against an alternative. It stops short of stating the converse (e.g. that it lists all payments when reference is omitted), so behavior in the no-reference case is left to inference.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds account scoping ('on your account') and the underlying endpoint (GET /reports), but says nothing about pagination, default limits, or ordering, which matter for a list endpoint.

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 primary action and resource. The trailing endpoint reference is marginally useful for agents mapping to Checkout.com's API but is otherwise low-value.

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-required-parameter list tool with no output schema, the description covers purpose but omits return shape, pagination behavior, and how the response is ordered or bounded. It is adequate but leaves real gaps an agent must discover at call time.

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%, with all four parameters (limit, entity_id, created_after, created_before) documented in the schema itself. The description adds no additional meaning about filtering or date formats, so the baseline 3 applies.

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

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

The description states a specific verb ('List') and resource ('reports available on your account') and gives concrete examples of report types (settlement, payments). It is clearly distinguishable from checkout_get_report by the list-vs-single framing, though it does not name that 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 checkout_get_report or any other sibling, nor any stated prerequisites or exclusions. Usage is only implied by the verb 'List'.

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 give destructiveHint=true, already signalling an irreversible mutation. The description usefully reinforces that money moves back and that partial refunds are possible, but adds nothing about idempotency, refund limits, or reversibility beyond what the hint implies.

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 the key effect (money back) stated first, followed by full/partial scope and endpoint. Slightly shouty capitalization but no wasted verbiage.

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 full schema coverage the description needn't explain returns, but for a destructive money-moving tool with minimal annotations it could say more about idempotency importance or refund constraints. 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 100%, so all five parameters (id, amount in minor units with default, metadata, reference, idempotency_key) are already documented. The description adds no parameter detail beyond the schema, 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?

Names a specific verb (refunds) and resource (a captured payment) plus the money-movement effect and the underlying endpoint. This distinguishes it from siblings like checkout_void_payment and checkout_capture_payment 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?

The description implies usage (refund a captured payment, full or partial) and states the endpoint, but gives no explicit when-to-use vs. checkout_void_payment or checkout_capture_payment, and no prerequisites such as needing a captured (not merely authorized) payment.

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, so the bar is lower, but the description adds real value by pre-empting confusion over the POST verb: 'this is a READ — it queries, it does not mutate.' It also discloses the underlying endpoint (POST /payments/search). It stops short of covering pagination behavior or result-set limits beyond the schema.

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

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

Three short sentences, front-loaded with purpose before the read-only clarification and the parameter hint. No filler, though the endpoint reference is arguably redundant for an agent that only needs the tool name.

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?

Adequate for a filter-based search with 100% schema coverage and no required params, and the read-only clarification closes the main behavioral gap. However, with nested filter/pagination objects and no output schema, the description does not sketch the shape of returned results, which an agent would need to chain calls.

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

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

Schema description coverage is 100%, so the baseline is 3. The description names the two parameter families ('query' filter object and 'paging fields') but adds no syntax, format, or field-level detail beyond what the schema already documents.

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 ('Search payments') plus the mechanism ('flexible query filters'), which is enough for an agent to grasp what it does. It does not, however, differentiate itself from the sibling checkout_list_payments, leaving the search-vs-list distinction to 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?

The description says to 'Pass a `query` filter object and/or paging fields', which implies usage (use it when you have filter criteria) but never states when to choose this over checkout_list_payments or checkout_get_payment. No prerequisites or exclusions are given.

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 annotation only carries destructiveHint=true, so the description does useful extra work by explaining the concrete effect: releasing the hold on the customer's funds. It omits whether a void can be reversed, what happens on an already-captured payment, and any idempotency/permission caveats, which is a real but modest gap.

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

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

Two tight clauses: the effectful clause first, then the API endpoint reference. No filler, nothing that restates the name or title.

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

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

For a single-payment mutation with no output schema, the description supplies the key operational context (state precondition, financial effect, backing endpoint). Error/failure behavior and irreversible-vs-reversible detail are the remaining omissions, but they are not required to call the tool correctly.

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

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

Schema description coverage is 100%, so the bare id, metadata, reference and idempotency_key semantics are already fully documented in the schema. The description adds nothing about parameter behavior (e.g. that idempotency_key maps to the Cko-Idempotency-Key header), so baseline 3 applies.

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

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

States a specific verb (voids/cancels), the resource (payment), and the exact state constraint (authorized but not yet captured), which cleanly separates it from checkout_capture_payment and checkout_refund_payment. An agent can pick it out of 18 siblings 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?

The phrase 'authorized but not yet captured' gives a clear precondition for use, so an agent knows which payments qualify. It stops short of naming alternatives or spelling out what to do for already-captured payments (refund) or already-voided ones, so it is context without explicit exclusions.

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