Skip to main content
Glama

Bernuvia

by com.bernuvia
OverviewDiscussionsAdmin

refund_sale

Voluntary refund of one of your owner's sales. IF YOU ARE THE ONE WHO COLLECTS THAT SALE (the template has your wallet as its payout destination), the contract only accepts your signature: you get the sellerRefund calldata for your linked wallet, you send it paying its gas and you come back here with { ordenId, confirmar: true, txHash } so the sale is recorded as refunded. IF YOUR OWNER COLLECTS IT, they sign it in My sales and here you only get the link to hand to them. It is only possible while the payment is still in escrow, with NO open dispute and BEFORE the deadline expires; it returns the FULL amount, the buyer loses the download and it cannot be undone.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
txHashNoOnly for the agent that gets paid for this sale, and AFTER sending the sellerRefund transaction: its hash. With it, Bernuvia reads the chain and leaves the sale recorded as refunded without waiting for the cron. It sends nothing and does not sign again.
confirmNoMANDATORY true. The refund returns the FULL amount to the buyer, with no fee and with no way back: the seller gets nothing for that sale and the buyer loses the download. Set it only if the person asked for it.
ordenIdNoDEPRECATED alias of `orderId`: it still works, but use `orderId` (it will be removed in a future round, no date yet). The ordenId (uuid) of YOUR sale, exactly as my_sales returns it.
orderIdNoThe ordenId (uuid) of YOUR sale, exactly as my_sales returns it.
confirmarNoDEPRECATED alias of `confirm`: it still works, but use `confirm` (it will be removed in a future round, no date yet). MANDATORY true. The refund returns the FULL amount to the buyer, with no fee and with no way back: the seller gets nothing for that sale and the buyer loses the download. Set it only if the person asked for it.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
okYesAlways true: a refusal travels as an error.
signAtNoOnly for a person: the link that opens the confirmation in My sales.
walletNoOnly with calldata: the only wallet the contract accepts for signing.
networkNoOnly with calldata: the network it has to be sent on.
orderIdYesThe uuid of the sale.
warningNoWhat the refund implies and that it cannot be undone.
contractNoOnly with calldata: the escrow contract of THIS order.
estadoBdNoOnly with txHash: the state the sale ended up in after reading the chain.
templateNoName of the template sold.
amountUsdcNoFull amount that goes back to the buyer, in USDC (decimal string).
deadlineAtNoUntil when the refund is still possible (ISO 8601): after that the payment is released.
purchaseIdNoThe orderHash of the sale (bytes32).
pollSecondsNoHow many seconds it makes sense to wait before asking again (0 = it is already done).
transactionNoOnly with calldata: the sellerRefund transaction, ready to sign.
instructionsYesWhat to do now: one sentence, or a list of sentences when the calldata is handed over.
sincronizadoNoOnly with txHash: whether this call actually changed the row.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed32 schema fields changed
    • changedInput schema / properties / confirm / description
      Previous value: -"OBLIGATORIO true. El reembolso devuelve el importe ÍNTEGRO al comprador, sin comisión y sin vuelta atrás: el vendedor no cobra nada por esa venta y el comprador pierde la descarga. Márcalo solo si la persona lo pidió."New value: +"MANDATORY true. The refund returns the FULL amount to the buyer, with no fee and with no way back: the seller gets nothing for that sale and the buyer loses the download. Set it only if the person asked for it."
    • changedInput schema / properties / confirmar / description
      Previous value: -"ALIAS RETIRADO de `confirm`: sigue funcionando, pero usa `confirm` (se quitará en una tanda futura, aún sin fecha). / DEPRECATED alias of `confirm`. OBLIGATORIO true. El reembolso devuelve el importe ÍNTEGRO al comprador, sin comisión y sin vuelta atrás: el vendedor no cobra nada por esa venta y el comprador pierde la descarga. Márcalo solo si la persona lo pidió."New value: +"DEPRECATED alias of `confirm`: it still works, but use `confirm` (it will be removed in a future round, no date yet). MANDATORY true. The refund returns the FULL amount to the buyer, with no fee and with no way back: the seller gets nothing for that sale and the buyer loses the download. Set it only if the person asked for it."
    • changedInput schema / properties / ordenId / description
      Previous value: -"ALIAS RETIRADO de `orderId`: sigue funcionando, pero usa `orderId` (se quitará en una tanda futura, aún sin fecha). / DEPRECATED alias of `orderId`. El ordenId (uuid) de TU venta, tal y como lo devuelve my_sales."New value: +"DEPRECATED alias of `orderId`: it still works, but use `orderId` (it will be removed in a future round, no date yet). The ordenId (uuid) of YOUR sale, exactly as my_sales returns it."
    • changedInput schema / properties / orderId / description
      Previous value: -"El ordenId (uuid) de TU venta, tal y como lo devuelve my_sales."New value: +"The ordenId (uuid) of YOUR sale, exactly as my_sales returns it."
    • changedInput schema / properties / txHash / description
      Previous value: -"Solo para el agente que cobra esta venta y DESPUÉS de enviar la transacción sellerRefund: su hash. Con él, Bernuvia lee la cadena y deja la venta registrada como reembolsada sin esperar al cron. No envía nada ni vuelve a firmar."New value: +"Only for the agent that gets paid for this sale, and AFTER sending the sellerRefund transaction: its hash. With it, Bernuvia reads the chain and leaves the sale recorded as refunded without waiting for the cron. It sends nothing and does not sign again."
    • changedOutput schema / properties / amountUsdc / description
      Previous value: -"Importe íntegro que vuelve al comprador, en USDC (cadena decimal)."New value: +"Full amount that goes back to the buyer, in USDC (decimal string)."
    • changedOutput schema / properties / contract / description
      Previous value: -"Solo con calldata: el contrato de custodia de ESTA orden."New value: +"Only with calldata: the escrow contract of THIS order."
    • changedOutput schema / properties / contract / properties / version / description
      Previous value: -"Versión del escrow de la orden."New value: +"Escrow version of the order."
    • changedOutput schema / properties / deadlineAt / description
      Previous value: -"Hasta cuándo cabe el reembolso (ISO 8601): después el pago se libera."New value: +"Until when the refund is still possible (ISO 8601): after that the payment is released."
    • changedOutput schema / properties / estadoBd / description
      Previous value: -"Solo con txHash: el estado en el que quedó la venta tras leer la cadena."New value: +"Only with txHash: the state the sale ended up in after reading the chain."
    • changedOutput schema / properties / instructions / description
      Previous value: -"Qué hacer ahora: una frase, o una lista de frases cuando se entrega el calldata."New value: +"What to do now: one sentence, or a list of sentences when the calldata is handed over."
    • changedOutput schema / properties / network / description
      Previous value: -"Solo con calldata: la red en la que hay que enviarla."New value: +"Only with calldata: the network it has to be sent on."
    • changedOutput schema / properties / network / properties / chainId / description
      Previous value: -"Id de la cadena."New value: +"Id of the chain."
    • changedOutput schema / properties / ok / description
      Previous value: -"Siempre true: una negativa viaja como error."New value: +"Always true: a refusal travels as an error."
    • changedOutput schema / properties / orderId / description
      Previous value: -"El uuid de la venta."New value: +"The uuid of the sale."
    • changedOutput schema / properties / pollSeconds / description
      Previous value: -"Cada cuántos segundos tiene sentido volver a preguntar (0 = ya está)."New value: +"How many seconds it makes sense to wait before asking again (0 = it is already done)."
    • changedOutput schema / properties / purchaseId / description
      Previous value: -"El orderHash de la venta (bytes32)."New value: +"The orderHash of the sale (bytes32)."
    • changedOutput schema / properties / signAt / description
      Previous value: -"Solo para una persona: el enlace que abre la confirmación en Mis ventas."New value: +"Only for a person: the link that opens the confirmation in My sales."
    • changedOutput schema / properties / sincronizado / description
      Previous value: -"Solo con txHash: si esta llamada llegó a cambiar la fila."New value: +"Only with txHash: whether this call actually changed the row."
    • changedOutput schema / properties / template / description
      Previous value: -"Nombre de la plantilla vendida."New value: +"Name of the template sold."
    • changedOutput schema / properties / transaction / description
      Previous value: -"Solo con calldata: la transacción sellerRefund lista para firmar."New value: +"Only with calldata: the sellerRefund transaction, ready to sign."
    • changedOutput schema / properties / transaction / properties / calculatedAt / description
      Previous value: -"Cuándo se calcularon las tarifas (ISO 8601)."New value: +"When the fees were computed (ISO 8601)."
    • changedOutput schema / properties / transaction / properties / data / description
      Previous value: -"Calldata codificado."New value: +"Encoded calldata."
    • changedOutput schema / properties / transaction / properties / description / description
      Previous value: -"Qué hace esa transacción."New value: +"What that transaction does."
    • changedOutput schema / properties / transaction / properties / gasLimitSuggested / description
      Previous value: -"Gas sugerido (cadena de dígitos)."New value: +"Suggested gas (digit string)."
    • changedOutput schema / properties / transaction / properties / maxFeePerGasSuggested / description
      Previous value: -"Tarifa máxima sugerida, si se pudo leer."New value: +"Suggested max fee per gas, if it could be read."
    • changedOutput schema / properties / transaction / properties / maxPriorityFeePerGasSuggested / description
      Previous value: -"Propina máxima sugerida, si se pudo leer."New value: +"Suggested max priority fee per gas, if it could be read."
    • changedOutput schema / properties / transaction / properties / name / description
      Previous value: -"Nombre de la función (sellerRefund)."New value: +"Name of the function (sellerRefund)."
    • changedOutput schema / properties / transaction / properties / to / description
      Previous value: -"Dirección del contrato de custodia."New value: +"Address of the escrow contract."
    • changedOutput schema / properties / transaction / properties / value / description
      Previous value: -"Valor en hexadecimal; siempre \"0x0\"."New value: +"Value in hexadecimal; always \"0x0\"."
    • changedOutput schema / properties / wallet / description
      Previous value: -"Solo con calldata: la única wallet que el contrato admite para firmar."New value: +"Only with calldata: the only wallet the contract accepts for signing."
    • changedOutput schema / properties / warning / description
      Previous value: -"Qué implica el reembolso y que no se puede deshacer."New value: +"What the refund implies and that it cannot be undone."
  2. First observed

TDQS

A4.9/5.0
Behavior5/5

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

With no annotations available, the description provides extensive behavioral disclosure: it is irreversible, returns the full amount, buyer loses download, contract accepts only the seller's signature, requires sending gas, and requires a follow-up with txHash. This fully compensates for the lack of annotations.

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

Conciseness5/5

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

The description is dense but every sentence adds essential information. It front-loads the purpose, then gives conditional workflow branches, then constraints and consequences, with no filler. The length is justified by the number of critical behavioral details.

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

Completeness5/5

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

The description covers the full lifecycle: who signs, how gas is paid, how to confirm, when it is allowed, what happens to funds and downloads, and irreversibility. With the output schema present, no key operational detail is missing for correct invocation.

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

Parameters4/5

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

The schema already documents all parameters with 100% coverage, so the baseline is 3. The description adds workflow-level meaning by explaining the expected call sequence: send the sellerRefund transaction with gas, then return with { ordenId, confirmar: true, txHash }. It reinforces that confirm/confirmar must be true and that txHash is only used after the on-chain transaction.

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

Purpose5/5

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

The description states a precise verb and resource: a voluntary refund of one of your owner's sales. It clearly differentiates itself from dispute-related siblings by describing the refund action, escrow conditions, and irreversibility. An agent can understand exactly what this tool does.

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

Usage Guidelines5/5

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

The description explicitly distinguishes between two scenarios: when the agent collects the sale and must sign, versus when the owner collects it and handles it in My Sales. It also gives clear conditions for when refund is possible (escrow, no dispute, before deadline) and lists exclusions. This tells the agent when to use this tool and when to defer to the owner.

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

All Bernuvia toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources