Checkout.com MCP by usefulapi

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

Annotations only provide destructiveHint=true; the description goes beyond that by flagging that this MOVES MONEY and settles the authorized amount, which is critical behavioral context. It still omits failure handling, reversibility, and whether partial captures can be repeated, so it falls short of a 5.

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

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

Two short clauses, with the money-movement warning front-loaded and capitalized for emphasis, followed by the concrete API endpoint. Every element 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 money-moving mutation with no output schema and sparse annotations, the description covers the essential 'what happens' and 'which endpoint' details. It could still be more complete about idempotency behavior and error/retry semantics for a financial operation.

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

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

Schema coverage is 100%, so all five parameters, including idempotency_key and metadata, are already documented in the schema. The description only adds that capture can be partial, echoing the amount parameter rather than adding new semantics; 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 precise verb+resource (captures a payment) and the scope of the operation (settles the full or partial authorized amount). It is easily distinguished from siblings like checkout_refund_payment or checkout_void_payment because it explicitly says the payment was previously authorized.

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 helpful. However, it never names alternatives (e.g., refund vs. void vs. capture) or states when NOT to use this tool, leaving routing decisions 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?

Annotation coverage is thin — only destructiveHint=true — so the description must add value, and it does state this is an additive write ('This ADDS data to your account'). It does not mention authentication, rate limits, whether a duplicate email fails, or idempotent retry behaviour, so it only partially fills the 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 short sentences plus an endpoint reference; the mutation nature is front-loaded with no filler. The all-caps emphasis and the raw endpoint string are slightly noisy but do not waste much space.

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 6-parameter creation tool with full schema coverage and no output schema, the essentials are present: what is created, that it is a write, and what the record is used for. Missing pieces are the response shape (e.g. returned customer id) and the duplicate-email/idempotency consequences, which an agent would want before retrying.

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 each field (name, email uniqueness, phone shape, default instrument id, metadata, idempotency key) is documented in the schema itself. The description adds no parameter-level 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?

The description states a specific verb and resource ('CREATES a customer record') and clarifies the business role of the record — a container for saved instruments and future payments. That is enough to distinguish it from the payment/refund/list siblings, though 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?

Usage is only implied via the parenthetical about attaching saved instruments and future payments, which hints at when a customer must exist first. There is no explicit when-to-use vs when-not, and no mention of prerequisites such as calling get_customer first to avoid duplicates (despite email needing to be unique).

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 supply destructiveHint=true, so the description carries most of the behavioral weight and does it well by hammering the money-movement and charge semantics. It stops short of disclosing auth/permission requirements, what a capture=false authorization leaves behind, or error/decline behavior, so it is strong but not complete.

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

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

Front-loads the highest-stakes fact (money movement) before mechanics, and every sentence carries information. The capitalized emphasis is slightly heavy-handed and the source-object examples echo the schema, so it is efficient but not maximally tight.

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

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

For an 11-parameter, nested-object, money-moving tool with no output schema, the description leaves the agent without any picture of the response (payment id, status, authorization outcome) or of idempotent-retry behavior beyond the schema's one-line hint. The required core is covered, but the gaps matter at this complexity level.

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, including the minor-units convention and idempotency key. The description restates `amount`/`currency` and gives `source` object examples that largely duplicate the schema, adding marginal value only. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('CREATES a payment') and immediately disambiguates the two modes (authorization vs. immediate capture) plus the underlying API call (POST /payments). The 'MOVES MONEY: charges a card' framing separates it cleanly from siblings like checkout_capture_payment, checkout_refund_payment, and checkout_void_payment.

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 implies when to use the tool (new payment, either authorize-only or immediate capture), which is useful context, but it never names alternatives or exclusions — nothing tells the agent to prefer checkout_capture_payment for an already-authorized payment or checkout_refund_payment to reverse one. Usage is inferable rather than explicit.

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 supply destructiveHint=true, which is unintuitive for a creation tool and goes unexplained. The description usefully adds that the result is a hosted, shareable link and that it produces a URL, but it says nothing about required API credentials, the meaning of the destructive hint, or that idempotency_key guards against duplicate links.

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

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

Three short sentences, front-loaded with the action and its purpose. The 'POST /payment-links' endpoint reference is the only mild filler, since an agent invoking this tool cannot use the raw path.

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 11 parameters, nested objects, and no output schema, the description correctly fills the biggest structural gap by stating that a shareable URL is returned. It is otherwise complete enough for invocation, though it omits any note on the idempotency behavior that the schema exposes.

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%, including the critical 'minor units' note for amount, so the schema carries all parameter meaning. The description adds no syntax or format detail beyond it, 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 business effect ('sets up a way to COLLECT MONEY'), and gives the backing endpoint. This is clearly distinguishable from the read-side sibling checkout_get_payment_link.

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 establishes a general context (collecting money from a customer) but never states when to prefer this over alternatives like checkout_create_payment, nor any preconditions or exclusions. No routing guidance is offered.

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 the underlying GET endpoint as a useful anchor, but says nothing about authentication requirements, rate limiting, or what happens when the id/email is not found. With annotations carrying the safety signal, this is adequate rather than 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?

Two tight clauses: the return payload and accepted identifier forms come first, the API endpoint last. Every element 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?

There is no output schema, so the description compensates by listing the returned fields (email, name, phone, saved instruments), which is exactly what an agent needs. For a one-parameter read-only tool this is close to complete, with only error/not-found behavior left 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% and the single 'id' parameter is fully documented there. The description restates the same 'cus_...' or email formats rather than adding new meaning such as validation rules or fallback behavior when both a customer id and an email exist.

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

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

States a specific verb and resource ('Get a customer's details'), enumerates what comes back (email, name, phone, saved instruments), and pins the API endpoint. An agent can distinguish it from checkout_create_customer or the other get_* 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 description implies when the tool applies by naming the two lookup modes (id or email), but it never states when to prefer this over siblings such as checkout_get_instrument or checkout_search_payments, nor any prerequisites. Usage is inferable but not spelled out.

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 establishes this is a safe read. The description adds the concrete shape of what is returned, which is modestly useful, but says nothing about auth requirements, rate limits, or behavior for unknown/expired 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 and resource, followed by a compact list of returned fields and the endpoint. No filler.

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

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

With no output schema, the description usefully enumerates the fields returned and identifies the REST endpoint, which is enough for an agent to call and interpret it. Only the sibling-routing guidance 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% with a single required 'id' parameter, and the schema itself documents the 'dsp_...' format. The description merely repeats that prefix, 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 (get), resource (single dispute), the id prefix 'dsp_...', and enumerates the returned fields (reason code, amount, deadline, evidence status). It is clearly distinguishable from the sibling checkout_list_disputes by scope.

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 'by id' – fetch one dispute when the id is known – but it never explicitly contrasts with checkout_list_disputes or says when a detail fetch is appropriate versus a listing. Adequate but with a clear gap.

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

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

Annotations declare readOnlyHint=true, so the safety profile is already covered. The description adds the important qualifier that rates are 'indicative' and identifies the rate provider, which is useful context. However, it does not describe return format, rate validity, authentication needs, or other behavioral details, so it remains at the minimum-viable level for an annotated read tool.

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

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

The description is two short sentences, with the main purpose front-loaded. The second sentence restates the HTTP endpoint, which is largely redundant with the tool name and title, but it is brief and not harmful. Overall efficient with minor waste.

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

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

The tool is simple, the schema is fully described, and annotations cover read-only safety. However, with no output schema, the description does not explain what the returned rates look like (e.g. rate format, pair ordering), and it lacks usage guidance. It is adequate but leaves clear gaps for an agent to infer.

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 schema. The description adds no parameter-level syntax, formats, or constraints beyond the schema. Baseline 3 is appropriate when the schema does all 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 ('Get') and resource ('indicative foreign-exchange rates Checkout.com uses'), and the parenthetical example ('e.g. for card payouts') further scopes the purpose. It is clearly distinct from all sibling tools, which deal with payments, customers, disputes, and reports.

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 an example context ('for card payouts') but does not state when to use this tool versus alternatives, nor does it include any exclusions or prerequisites. Usage is only implied by the example, fitting the 'implied usage' level.

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. The description adds the underlying REST mapping (GET /instruments/{id}) and the tokenized nature of the resource, but says nothing about auth requirements, error behavior for unknown ids, or rate limits – the annotation carries most of the safety profile.

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, zero filler, with the core purpose front-loaded before the endpoint reference. Nothing is wasted.

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

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

For a trivial one-parameter read tool with annotations covering the safety profile and a fully documented schema, the description is sufficient. With no output schema, it could say a bit more about what the returned details include, but that is a minor gap.

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

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

Schema coverage is 100% and the single parameter is fully described there, including the 'src_...' format. The description merely repeats that id format, adding no semantics 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?

States a specific verb and resource ('Get the details of a saved payment instrument'), clarifies what that resource actually is (tokenized card / bank account), and pins the id format. It is distinct from the get_payment/get_customer siblings by resource, though it never names an alternative 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 guidance on when to use this versus the other lookup tools (get_customer, get_payment, search_payments) or any stated prerequisite. Usage is only implied by the id prefix, so an agent must infer the context itself.

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 establishes this as a safe read, and the description is consistent with that. It adds that payment session ids ('sid_') are also accepted, but says nothing about not-found behavior, error responses, or whether the returned detail set is bounded — minor gaps given the annotation covers the safety profile.

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

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

One sentence front-loads the resource and lookup key, followed by a short API mapping. No filler, nothing 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?

For a single-parameter, read-only lookup with a fully documented schema, the description covers what the tool returns at a high level ('full details'). No output schema exists, so a brief return-value characterization is the only remaining nicety, and 'full details of a payment' largely satisfies it.

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

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

Schema description coverage is 100% and both the format example ('pay_...') and the session-id variant are already documented in the schema. The description's 'pay_...' example is a restatement, so the baseline 3 applies.

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

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

States a specific verb ('Get'), resource ('payment / payment session'), and lookup key ('by its id'), and even maps to the underlying API (GET /payments/{id}). An agent can distinguish it from checkout_get_payment_actions or checkout_list_payments without opening another 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 only implied: you need a payment id, so this is the retrieval path once you have one. It never names alternatives such as checkout_get_payment_actions (for action history) or checkout_search_payments (when you lack the id), so the agent must infer the boundary.

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=true annotation already covers the safety profile, so the bar is lower. The description adds some behavioral value by listing the action types returned and specifying ordering ('latest first'), but discloses nothing about pagination, auth requirements, or error behavior for this 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 sentences, front-loaded with the core purpose and ordering, with no wasted words. The trailing endpoint reference is compact and informative.

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-only list tool with no output schema, the description covers what is returned and in what order. A note about pagination (common on list endpoints) would make it fully complete, but nothing essential to invoking the tool 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 fully documented in the schema (e.g., 'pay_...'). The description adds no syntax or format details beyond what the schema already provides, 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 ('actions ... associated with a payment') and enumerates the action types (authorization, capture, refund, void), making the tool's scope immediately clear and distinguishable from checkout_get_payment. It could name siblings explicitly, but the resource-scoping alone separates it from the other payment 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?

The description implies usage (auditing/retrieving the action history for a given payment) via 'associated with a payment, latest first,' but gives no explicit when-to-use or when-not-to-use guidance, and does not name an alternative such as checkout_get_payment. Usage is inferable but not directed.

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=true annotation already establishes the safe-read profile, so the description's job is lighter. It adds the id prefix convention and the underlying HTTP endpoint, but says nothing about auth requirements, error behavior for an unknown id, or response shape. With annotations covering 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 tight sentence: purpose first, id convention second, endpoint reference last. No filler sentences, and nothing an agent needs is 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?

There is no output schema, so the description carries some burden for return semantics; 'details and status' is a minimal gesture at the response but does not describe what fields come back or what status values mean. For a simple single-parameter read tool this is passable, but it leaves a real gap.

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

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

Schema description coverage is 100% for the single id parameter, so the baseline is 3. The description's 'e.g. pl_...' hint duplicates the schema's own example rather than adding new format or constraint information.

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) scoped by id, and distinguishes itself from the sibling checkout_get_payment by naming the resource explicitly. The appended REST endpoint (GET /payment-links/{id}) reinforces the operation unambiguously.

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 its id' phrasing, which tells the agent this is a single-record lookup rather than a list or search. However, it offers no explicit when-to-use guidance or distinction from alternatives such as checkout_get_payment or checkout_search_payments.

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 as a safe read operation. The description adds useful context by saying the response includes metadata and downloadable files, but it does not mention error behavior, pagination, or whether report generation must be complete first.

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 with no wasted words. The purpose and id format are front-loaded, and the API endpoint mapping is compact and useful.

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 a fully described id schema and readOnly annotation, the description is nearly complete and even notes that downloadable files are included. It falls short only on explicitly routing the agent from list_reports or explaining when a report id is valid.

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 id parameter is already fully documented in the schema, including the 'rpt_...' example. The description repeats that format but adds no meaning beyond the structured schema, 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: get metadata of a specific report by id. It also distinguishes retrieval by id from the sibling list_reports operation and names the id prefix, so an agent can tell what this tool does 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 'by id' implies this tool is used when a report id is already known, and the sibling list_reports suggests an alternative for discovery. However, the description never explicitly says when to use this versus list_reports or where to obtain the id, leaving usage 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds two genuinely useful behavioral facts beyond the annotations: the default ordering ('most-recently-modified first'), which matters for stable pagination, and the underlying endpoint (GET /disputes). It does not discuss rate limits or how filtering interacts with pagination.

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 zero filler; scope and sort order are front-loaded, and the endpoint mapping is a compact trailing clause that earns its place for API-literate agents.

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, fully-documented, zero-required-parameter list tool, the definition covers purpose, ordering and endpoint adequately. The main omission is any hint about the result envelope or total-count/pagination shape, which no output schema supplies.

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 8 parameters (from/to, skip, limit, statuses, entity_ids, payment_id, this_channel_only) are already documented with formats, defaults and bounds. The description adds no parameter-level meaning 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 and resource ('List disputes'), clarifies the synonym ('chargebacks'), and notes scope ('against your business'). It does not explicitly distinguish itself from the singular sibling checkout_get_dispute, but 'List' vs 'get' is reasonably self-evident.

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?

'With optional filters' implies browsing/filtering is the use case, and the sort order hints at recency-driven review. However, there is no explicit when-to-use guidance, no mention of when to prefer checkout_get_dispute for a single dispute, and no stated prerequisites.

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=true annotation already establishes the safety profile, so the bar is lower. The description adds minimal behavioral context beyond that: it identifies the underlying HTTP surface (GET /payments with query parameters) but says nothing about result ordering, default page size, or how results behave when reference is omitted. Adequate, 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?

Three short sentences, front-loaded with the purpose and ending with the disambiguation hint, which is the right ordering. The 'Checkout.com: GET /payments (query parameters)' clause is mildly redundant for an agent but plausibly useful for tracing the underlying API contract.

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 three-parameter read-only list tool with no output schema and fully documented parameters, the description covers purpose, filter scope, and the alternative tool. Only minor gaps remain: no statement about result shape or how pagination behaves when the payment set is large.

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 documented in the schema, which sets the baseline at 3. The description's 'match a given reference' restates the reference parameter rather than adding syntax or matching semantics (exact vs partial match) 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 and resource ('List your business's payments') plus the scoping filter ('that match a given reference'), and explicitly names the sibling it is not (checkout_search_payments). An agent can distinguish this from checkout_search_payments and checkout_get_payment 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 explicit routing guidance: use checkout_search_payments when richer filtering is needed, which cleanly separates it from the sibling. It does not spell out when this tool should NOT be used (e.g., when a single payment ID is already known and checkout_get_payment would be better), so it stops short of full when/when-not coverage.

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 safety, and the description reinforces it's a read operation ('List'). The description adds the resource scope (account-level reports) but doesn't cover pagination behavior, rate limits, or result shape — reasonable given annotations carry the safety profile.

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, front-loaded sentences with zero filler. 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?

For a read-only list tool with full schema coverage and annotations, the description is largely complete. It could note that results may need pagination via limit, and there's no output schema to describe return fields. Minor gaps only.

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

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

Schema description coverage is 100%, so each parameter is fully documented in the schema. The description adds no parameter-level detail beyond what's in the schema, which is the baseline 3 expectation.

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

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

Specific verb (list) + resource (reports) + clarifying examples (settlement, payments) and endpoint (GET /reports). Clearly distinguishable from sibling checkout_get_report which fetches a single report.

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?

Implied usage is clear from 'list' vs the sibling get_report, but no explicit when-to-use/when-not guidance or mention of the alternative is provided. Adequate but not exceptional.

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 declare destructiveHint=true and a title; the description adds genuinely useful context beyond that, making explicit that this MOVES MONEY BACK to the customer and supports both full and partial refunds. It does not cover auth requirements, reversibility, error modes, or the returned refund object, so it stops short of a 5.

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

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

A single front-loaded sentence carrying the verb, the scope, and the financial consequence, followed by the endpoint. Emphasis via capitalization is used sparingly and 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?

With no output schema, the description never says what a refund call returns (refund id, status) or how partial-refund totals behave across multiple calls, and it gives no idempotency/permission guidance. The 100%-covered input schema and destructiveHint annotation carry most of the load, so this is adequate but with a notable gap for a money-moving mutation.

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

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

Schema coverage is 100%, so the schema already documents id, amount (minor units, defaults to full captured amount), metadata, reference, and idempotency_key. The description's 'full or partial' adds a sliver of meaning about amount behavior but largely restates what the amount property already says — 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 (refund a captured payment) with the exact API operation (POST /payments/{id}/refunds), and the word 'captured' implicitly scopes it away from void_payment (uncaptured) and capture_payment. An agent can tell it apart from its siblings 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?

Usage is implied by 'refunds a captured payment' — the agent can infer this applies to already-captured payments — but there is no explicit guidance on when to choose this over checkout_void_payment or checkout_capture_payment, nor any stated prerequisites (e.g., the payment must be in a refundable state).

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, but the description adds genuinely useful context beyond them: the endpoint is POST /payments/search, and it explicitly flags that a POST here is a READ that does not mutate. That preempts a real misreading. It still says nothing about result caps, cursor lifecycle, or rate limits.

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

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

Three short sentences, front-loaded with the verb+resource and the read-only note. The final sentence largely repeats what the schema already documents, so it is slightly redundant but not wasteful.

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 should carry at least a hint of the response shape and cursor reuse, and it does not. The nested, open-ended filter objects (additionalProperties) also imply flexible semantics that are never described, though annotations cover the safety profile.

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 limit, query, and pagination are already documented with examples ({ reference, id, status, currency, amount, from, to } and { after, before }). The description only restates that query and paging fields are accepted, adding no syntax or constraint detail beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('Search payments') plus the underlying endpoint (POST /payments/search), so the agent knows exactly what operation this is. It does not explicitly distinguish itself from the closest sibling, checkout_list_payments, leaving the search-vs-list choice 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?

It says to pass a query filter object and/or paging fields, which is parameter guidance rather than usage guidance. There is no statement of when to prefer this over checkout_list_payments or checkout_get_payment, and no exclusions or prerequisites.

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

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

Annotations already declare destructiveHint=true, so the safety profile is covered; the description adds real value by explaining the concrete effect (releases the hold on the customer's funds) and giving the underlying API route. It stops short of stating prerequisites such as required API scope, error cases, or whether a void can be undone.

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 zero filler; the destructive effect and the state precondition are front-loaded before the endpoint reference. Every clause carries information an agent can act on.

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 four-parameter mutation tool with no output schema, the description supplies the essential semantics: what is voided, in which state, and what the side effect is. It omits any hint of the returned void status or idempotency behavior, which would have closed the remaining gaps at no cost.

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, metadata, reference, and idempotency_key are all documented in the schema already, which sets the baseline at 3. The description adds no parameter-level meaning beyond implying the payment id is the path segment, so it neither helps nor hurts.

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) against a named resource (payment) and adds the qualifying state 'authorized but not yet captured', which is exactly what separates it from capture and refund operations. It does not name a sibling tool explicitly, so an agent must infer the boundary from the state condition rather than being told.

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' functions as a clear when-to-use precondition and implies when it should not be used (captured payments need refund instead). However, it never names checkout_refund_payment or checkout_capture_payment as the alternatives for those other states, leaving the routing inference to the agent.

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