Belgium Payments (Mollie — Bancontact)

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

The description goes beyond annotations by detailing idempotent behavior (returns existing subscription), non-error handling when mandate is not yet valid (returns activated=false with mandate_status), and the fact that plan parameters are stored on the first payment and not re-supplied. This adds significant behavioral insight beyond the annotations (idempotentHint: true, destructiveHint: false).

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

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

The description is a single, well-structured paragraph that efficiently covers prerequisite flow, behavior in both success and polling scenarios, idempotency, and parameter origin. Every sentence adds value with no redundancy.

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

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

For a tool with no output schema and moderate complexity, the description provides comprehensive context: the two-step flow, polling instructions, idempotency, and parameter sourcing. It explains what to expect (subscription_id or activated=false) and how to proceed if the mandate is not ready.

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

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

The input schema already describes both parameters with 100% coverage. The description adds meaningful context: customer_id and payment_id come from create_subscription_link, and payment_id carries stored plan parameters. This enhances understanding without simply repeating 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 clearly identifies the tool as the second step of the Mollie subscription flow, specifying it activates the subscription after the buyer's first payment. It mentions the inputs (customer_id and payment_id) and the output (subscription_id or activated=false). This distinguishes it from siblings like create_subscription_link, query_subscription, and cancel_subscription.

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

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

The description explains when to use the tool (after create_subscription_link and after the buyer has paid the first payment) and provides guidance on handling the case where authorization is not yet complete: poll with query_subscription, wait ~20s, then retry. It also notes idempotency. While it doesn't explicitly state when not to use it, the context is clear enough.

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?

Description adds behavioral details: cancellation is immediate, no further charges. Handles edge case about unauthorized mandate. Annotations already indicate destructive but description enriches understanding.

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?

Concise: four sentences covering purpose, instructions, behavior, and edge case. No fluff.

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?

Covers purpose, prerequisites, behavior, and edge case. Does not explicitly state the return value on success, but for a mutation tool this is acceptable. Mostly complete.

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 descriptions already specify the format and source for subscription_id. Description does not add new semantic information for customer_id beyond the schema. Therefore baseline 3.

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

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

The description clearly states the tool cancels a Belgium subscription to stop charging. It specifies required parameters from related tools and distinguishes from siblings like activate_subscription and query_subscription.

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

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

Provides explicit guidance: use the subscription_id from activate_subscription or query_subscription. Also states when not to use (if mandate not authorized). Clear 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 description adds substantial behavioral context beyond annotations: payment completes automatically with no confirm step, authentication via HTTP header, money flow buyer->Mollie->merchant, and that the service never touches funds. The annotations (readOnlyHint=false, destructiveHint=false) are consistent, and no contradictions exist.

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 concise (4 sentences) and front-loaded with the core purpose. Each sentence serves a distinct purpose: stating the action, payment method, output and process, and security model. No redundant or vague statements.

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?

Given the absence of an output schema, the description adequately explains the return value (hosted checkout URL). It covers authentication, payment flow, and safety. With a sibling tool for querying status, the description for creation is fully self-contained and sufficient for an agent to invoke 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?

The schema covers 100% of parameters with detailed descriptions (e.g., amount_eur with min/max, description length limit). The description adds value by mentioning the authentication header requirement, which is not in the schema. Since schema coverage is high, baseline is 3, but the extra context justifies a 4.

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

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

The description clearly identifies the action (create a payment link), the specific region and currency (EUR for Belgium), the payment method (Bancontact), and the output (hosted checkout URL). It distinguishes itself from the sibling tool query_payment_status by focusing on creation.

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 clear context: use for Belgium, EUR, Bancontact, and other methods. It explains the authentication requirement (x-mollie-api-key header) and mentions test credentials. However, it does not explicitly state when NOT to use this tool or provide direct comparison to the sibling.

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 provide basic flags (readOnlyHint=false, destructiveHint=false). The description adds crucial behavioral context: the honest two-step flow, that money never touches the service, the first payment authorizes the mandate, and returns a checkout URL. No contradictions.

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 lengthy but packed with necessary details. It front-loads the core purpose and constraints, then explains the flow. Every sentence serves a purpose, though some streamlining could improve conciseness.

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, but the description implies return values: 'returns a hosted checkout URL' and mentions 'customer_id and payment_id' for the next step. It does not explicitly list error scenarios or the return structure, but is sufficient for an AI agent to understand the response.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema, e.g., 'amount_eur charged PER billing period', 'total_count INCLUDES the first payment', 'interval multiplies period'. However, it could still be more explicit about some parameter interactions.

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

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

The description clearly states the verb 'Create', resource 'recurring subscription', and specific constraints (EUR, Belgium, Mollie). It distinguishes from siblings like create_payment_link and explicitly ties to activate_subscription. No ambiguity.

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 explains the two-step flow, when to use (for recurring subscriptions), and when to call activate_subscription. It mentions prerequisites (x-mollie-api-key) and guardrails, and implies alternatives (non-recurring use create_payment_link).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds behavioral details: it queries Mollie directly, is pull-based, and defines paid=true when status is PAID. No contradictions.

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 fluff, front-loaded with the core purpose. Every sentence adds essential 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?

Despite no output schema, the description explains the key behavioral output (paid=true when status is PAID). For a single-parameter check tool, this is complete.

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 adds value by specifying that payment_id is the one returned by create_payment_link, which provides context 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 clearly states the tool checks whether a Belgium payment (created by create_payment_link) has been paid, with a specific verb ('check') and resource ('payment status'). It distinguishes from the sibling tool create_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 provides context: queries Mollie directly (pull-based) with no webhook needed. It implies usage when you want a synchronous status check without webhooks, but doesn't explicitly state when not to use or contrast with 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?

Annotations declare readOnlyHint and openWorldHint. The description adds rich behavioral context: status codes with implied actions (e.g., calling activate_subscription), returned fields like subscription_id and next_charge_date, and polling suggestion. No contradiction with annotations.

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

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

The description is a single dense paragraph, front-loaded with purpose and structured by two modes using colons. It contains no filler, but could be slightly more formatted for machine readability (e.g., bullet points). Still concise and 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?

Given no output schema, the description covers key scenarios: two parameter modes, expected statuses, and when to take next steps. It lacks error handling or rate limits, but for a read-only check tool, it provides sufficient context for correct 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 coverage is 100% with basic descriptions. The description adds meaning by explaining where each ID comes from (create_subscription_link, activate_subscription) and how omitting vs including subscription_id affects the response. This enhances parameter understanding beyond 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 clearly states the tool checks a Belgium subscription, distinguishing two distinct modes: passing customer_id alone for mandate overview or with subscription_id for specific status. This separates it from siblings like activate_subscription or cancel_subscription.

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

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

The description explicitly explains when to use each parameter combination: customer_id alone for mandate status, both IDs for direct subscription check. It also notes pull-based nature. However, it does not explicitly state when not to use or mention alternatives beyond the tool 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?

The description discloses that refunds are destructive (consistent with destructiveHint=true) and not idempotent (by implication of partial vs full refund). It adds context about policy checks (x-agentpay-max-amount) before gateway submission, which goes beyond annotations. No mention of idempotency behavior or error states, but annotations already cover safety hints.

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: first states core action and default, second adds policy guardrails. No redundant or extraneous information. Well-structured and easy to parse.

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?

Given no output schema, the description could hint at the response (e.g., refund confirmation). However, it covers input parameters, default behavior, partial refund capability, and policy constraints. Sibling tools are listed in context signals. Slightly incomplete on return value, but overall adequate.

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?

Both parameters are fully described in the schema (100% coverage). The description adds value by clarifying that payment_id is the same as used in query_payment_status and that amount is in local currency major unit for partial refunds. This helps the agent correlate parameters across tools.

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 explicitly states 'Refund a paid payment' and ties it to a specific creator tool (create_payment_link). It clearly distinguishes from siblings: create_payment_link creates payments and query_payment_status checks status, while refund_payment processes refunds.

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 explains default behavior (full refund) and optional partial refund via 'amount' parameter. It also references owner policy guardrails, giving context for when the tool can be used. It does not explicitly state when not to use or suggest alternatives, but the guidance is sufficient for typical usage.

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