Skip to main content
Glama
tersignhq

tersign

Official
by tersignhq
OverviewSchemaSourceRelated ServersScoreDiscussions(2)Admin
TypeScript
Remote

Record refund

record_refund

Record an already-issued refund against the original receipt as the seller, producing a counter-signed, append-only entry that keeps charge and refund visible.

Instructions

Record a refund against an already-chained receipt, as the SELLER. The refund becomes its own counter-signed entry that references the original — nothing is edited or deleted, so the chain stays append-only and both the charge and the refund remain visible. Requires ledger configuration (TERSIGN_LEDGER_URL/_API_KEY/_SELLER_ID) and performs one network write; errors if the original digest is not on your chain. This RECORDS a refund you have already made — it moves no money. Returns the refund record, its digest, the ledger counter-signature and sequence number.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
amountYesrefunded amount as a decimal STRING in the original settlement currency, e.g. "12.50". A string, not a number, so no precision is lost. Partial refunds are allowed
reasonYeswhy the refund was issued, in your own words; recorded verbatim for whoever reads the chain later
originalDigestYes0x-prefixed keccak256 digest of the receipt being refunded — the digest returned by issue_receipt, and it must already exist on your chain

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.4.7
    • addedInput schema / properties / amount / description
      Added value: +"refunded amount as a decimal STRING in the original settlement currency, e.g. \"12.50\". A string, not a number, so no precision is lost. Partial refunds are allowed"
    • addedInput schema / properties / originalDigest / description
      Added value: +"0x-prefixed keccak256 digest of the receipt being refunded — the digest returned by issue_receipt, and it must already exist on your chain"
    • addedInput schema / properties / reason / description
      Added value: +"why the refund was issued, in your own words; recorded verbatim for whoever reads the chain later"
  2. First observedv0.2.0

TDQS

A4.4/5.0
Behavior5/5

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

With no annotations provided, the description carries the full burden, and it delivers: it discloses append-only immutability ('nothing is edited or deleted'), the network write side effect, environment prerequisites, the error condition for a missing original digest, and the semantic limitation that it moves no money. This is exemplary behavioral disclosure.

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

Conciseness4/5

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

Four sentences, each carrying distinct value: role/purpose, chain semantics, requirements/error behavior, and semantic boundary/return values. There is no filler, though the description is slightly longer than strictly necessary; it remains well-structured and front-loaded.

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?

Given no output schema and no annotations, the description is unusually complete: it states prerequisites (ledger config), side effect (one network write), error condition (digest not on chain), role constraint, and return values (record, digest, counter-signature, sequence number). An agent has what it needs to invoke the tool correctly without digging elsewhere.

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

Parameters3/5

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

The input schema already documents all three parameters with 100% coverage, including amount as a precision-preserving decimal string, reason as verbatim text, and originalDigest with regex pattern and existence requirement. The description adds essentially no new parameter-level meaning beyond what the schema states (e.g., original digest must exist), so a baseline 3 is appropriate.

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 opens with 'Record a refund against an already-chained receipt, as the SELLER', stating a specific action, target resource, and role. It clearly distinguishes this from issue_receipt and other tools by focusing on refunds of already-chained receipts and explicitly noting it records an already-made refund rather than creating the original charge.

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

Usage Guidelines4/5

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

The description gives clear context: use this when you are the seller and have already made a refund, and you need to record it against an existing receipt. It also clarifies a boundary ('moves no money') and a prerequisite (ledger configuration). It does not explicitly name alternative tools or list when-not-to-use conditions, so it falls just short of a 5.

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

Install Server

Other Tools