Bulgaria Payments (Stripe — cards / Apple Pay)

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

The description adds context beyond annotations: default cancellation keeps subscription active until period end, and immediate cancellation is available. This is consistent with destructiveHint=true and readOnlyHint=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?

Description is two sentences, no wasted words, and directly addresses the core behavior and key parameter.

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

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

Given no output schema, the description covers the essential behavior. It could mention what the response looks like (e.g., success status), but is still adequate for a cancellation action.

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%, baseline 3. The description explains the 'immediate' parameter's effect and default behavior, adding meaning beyond the schema's description. The 'id' parameter is already well-described in 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 'Cancel a subscription' with the verb and resource, and distinguishes behavior based on the 'immediate' parameter, differentiating from sibling tools like 'refund_payment' or '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?

The description explains when to use 'immediate=true' vs default (end of period), and implies fairness to the buyer. However, it does not explicitly state when not to use this tool or compare 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?

Exceeds annotation info: details payment flow (auto-completion, no confirm step), credential requirement via header, money flow (buyer→Stripe→merchant, service never touches funds), and optional invoice/tax ID features.

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?

Single paragraph is informative but could be more structured. Every sentence adds value; no redundancy. Slightly long but appropriate for the complexity.

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 all essential aspects: purpose, payment flow, credentials, money handling, optional features, return value. No output schema but description explains return. Complete for an AI agent to use 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?

Adds context beyond schema descriptions (e.g., issue_invoice creates VAT-ready PDF invoice, collect_tax_id for tax ID on invoice). Schema coverage is 100%, so description complements rather than repeats.

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?

Clearly states it creates a payment link for Bulgaria in BGN via Stripe Checkout Sessions. Distinguishes from sibling tools like create_subscription_link, cancel_subscription, etc., by specifying it's for one-time payments.

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?

Implies usage for one-time BGN payments in Bulgaria, with options for invoicing and tax ID collection. Not explicitly stating when not to use or comparing with alternatives, but sibling context makes it clear.

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 indicate non-read-only, non-idempotent, non-destructive. Description adds behavioral details: Stripe integration, automatic recurring charges, guardrails. No contradictions. Could mention side effects more explicitly (e.g., charge initiation), but sufficient.

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: first sentence states purpose clearly, second adds workflow and guardrails. No wasted words, front-loaded, 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 5 parameters, full schema coverage, no output schema, the description explains the checkout flow and key constraints. Could mention what the tool returns (the URL) but not necessary; overall complete enough.

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 clear descriptions. The description reinforces amount_bgn as per-period local currency and notes optional nature of success_url and customer_email, but adds minimal new meaning 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 it creates a recurring subscription checkout link via Stripe, with specific verb 'create' and resource 'subscription link'. It distinguishes from sibling 'create_payment_link' which handles one-time payments, and implies recurring billing.

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 (for recurring subscriptions) and the buyer experience. It mentions the per-period amount and guardrails. However, it does not explicitly state when not to use or directly name alternatives like create_payment_link, though it's implied.

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 querying Stripe directly as a behavioral trait, and specifies output conditions (paid=true when status is PAID, invoice fields if issue_invoice was true). Annotations already mark readOnlyHint and openWorldHint, and description adds useful context without contradiction.

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 sentences with no filler. Front-loaded with the main purpose, followed by behavioral and output details. Every sentence adds 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 simple tool with one parameter and no output schema, the description fully explains input (session_id), output (paid, invoice_url, invoice_pdf), and behavior (direct Stripe query). No 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?

The only parameter 'session_id' is described in schema as returned by create_payment_link, and the description repeats that. With 100% schema coverage, the description adds minimal extra value, meeting baseline but not exceeding.

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 payment status for Bulgaria payments created by create_payment_link. It specifies the resource (payment status) and action (check), distinguishing it from sibling tools like refund_payment or 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?

The description explicitly says 'pull-based, no webhook needed', indicating when to use without waiting for webhooks. It provides context that it's for Bulgaria payments from create_payment_link, though it doesn't explicitly list alternatives or when-not-to-use.

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 indicate readOnlyHint and openWorldHint. The description adds behavioral context by explaining the meaning of 'active=true' and the 'NOT_SUBSCRIBED_YET' status, providing insight into output interpretation beyond mere read-only semantics.

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 convey purpose, input format, and key output interpretations. No extraneous words, and the most critical information is front-loaded.

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?

While the description covers core usage and status meanings, it does not enumerate all possible subscription statuses or error conditions. The output format is partially described, leaving some gaps for an agent relying solely on this description.

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 fully describes the 'id' parameter, and the description merely echoes that information without adding new semantics. Baseline 3 applies due to high schema 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?

The description explicitly states it checks a subscription created by create_subscription_link, and specifies the input types. This clearly distinguishes it from sibling tools like cancel_subscription or query_payment_status, which serve different purposes.

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 indicates the tool is for subscriptions specifically from create_subscription_link, and mentions acceptable ID formats. It does not explicitly contrast with sibling tools, but the context signals and naming imply when to use it.

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

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

Annotations indicate destructive behavior, and the description adds valuable context: refunds respect the x-agentpay-max-amount guardrail and are checked before gateway processing. It also clarifies that partial refunds are only supported where available. 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 three sentences, each earning its place: first states purpose, second explains default vs partial refund, third discloses guardrails. No extraneous 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?

The description covers usage and behavioral context well, but it lacks information about the return value or response format (no output schema), and does not mention non-idempotency or prerequisites (e.g., payment must be in a refundable state). Given the complexity, it misses some completeness.

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 covers both parameters with descriptions, but the tool description adds extra meaning: it explains that amount is for partial refunds (where supported) and that omitting it triggers a full refund, and relates session_id to query_payment_status. This exceeds the baseline for full schema 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?

The description clearly states 'Refund a paid payment (created by create_payment_link)', specifying the action (refund) and resource (paid payment), and distinguishes from other tools by mentioning the specific origin of the 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?

The description tells when to use the tool (to refund a paid payment) and how to do a partial refund, but it does not explicitly state when not to use it or mention alternative tools. However, the context is clear enough for correct usage.

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