Create a bank-transfer payment

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

The description carries substantial behavior beyond the annotations: it discloses the side effect (a dynamic virtual account is provisioned and expires with the payment), specific error contracts (`400 expiry_out_of_range` with `details.min_seconds`/`max_seconds`, `409 duplicate_reference`), and the success condition tied to a webhook event. This does not conflict with `idempotentHint: false` — the annotation correctly says a repeat call would create a second payment, and the description explains the caller-supplied key that prevents it.

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?

Paragraphs are front-loaded and each carries a distinct operational fact (account handoff, amount rule, expiry, success semantics, uniqueness/idempotency), so there is little filler. The one flaw is the opening sentence duplicated almost verbatim ("Create a bank-transfer payment.\n\nCreate a bank-transfer payment."), which wastes the highest-attention position.

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 12-parameter creation tool with nested objects and no output schema, the description covers the full lifecycle an agent needs: what is created, what to show the customer, how long it lives, how success is proven, and the two failure modes it will most likely hit. Left unaddressed are the response envelope beyond the `bank_transfer` account and the untouched parameters (`split`, `expand`, `metadata`, `customer`).

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?

With 67% schema coverage, the description meaningfully extends the schema on the parameters that matter: it states the default for `amount_rule`, that `amount` becomes optional under `any`, the hard range and default for expiry, and the uniqueness constraint on `reference`. It does repeat some schema text verbatim (the 300–10800 expiry seconds) and says nothing about `split`, `expand`, `metadata`, `customer`, or `description`, leaving a quarter of the surface to the schema alone.

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

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

The description gives a specific verb and resource ("Create a bank-transfer payment") and immediately explains the mechanism — Pletopay opens a single-use virtual account returned under `bank_transfer` — which separates it functionally from payout tools like create_transfer and from create_checkout_session. It never names a sibling, so an agent must still infer the boundary between accepting a bank transfer and accepting a card checkout.

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 sets clear conditions for the key decisions: `amount_rule: exact` versus `any` (and that `amount` may then be omitted), the 5-minute-to-3-hour expiry window and its default, and when to send an Idempotency-Key. It also warns how NOT to confirm payment — don't trust a redirect or client-side callback, listen for `payment.succeeded` or retrieve the payment. The gap is that it never tells the agent when to pick this over create_checkout_session or create_payment_link.

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