Skip to main content
Glama

link_refund

Mark an existing transaction as a refund of another transaction. Provide originalTxId (the transaction being refunded) and refundTxId (the refund transaction). The two transactions must have opposite types (income vs expense). Optionally target a specific split of the original. One refund can cover several purchases: call once per purchase, each with an amount; the amounts cannot exceed the refund, and in the same currency the amounts against one purchase or split cannot exceed it. Requires finance:write scope.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "originalTxId": "<originalTxId>",
      "refundTxId": "<refundTxId>"
    },
    "name": "link_refund"
  }
}

Input Schema

NameRequiredDescriptionDefault
amountNoShare of the refund transaction (decimal, in the refund transaction's currency) that this link covers. Omit to link the whole refund. Required on every link when one refund covers several purchases.
splitIdNoUUID of a specific split on the original transaction this refund targets
refundTxIdYesID of the transaction that represents the refund
originalTxIdYesID of the original transaction being refunded. Pass null for a standalone refund

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / originalTxId / anyOf
      Previous value: -[
      -  {
      -    "format": "uuid",
      -    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "format": "uuid",
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • removedInput schema / properties / refundTxId / pattern
      Removed value: -"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
  2. Changed1 schema field changed
    • addedInput schema / properties / amount
      Added value: +{
      +  "description": "Share of the refund transaction (decimal, in the refund transaction's currency) that this link covers. Omit to link the whole refund. Required on every link when one refund covers several purchases.",
      +  "exclusiveMinimum": 0,
      +  "type": "number"
      +}
  3. First observed

TDQS

A4.3/5.0
Behavior4/5

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

With only readOnlyHint=false supplied, the description carries most of the burden and does so: it discloses the opposite-type precondition, the amount aggregation rule (amounts cannot exceed the refund or the targeted purchase/split in the same currency), and the required finance:write scope. It does not state reversibility or that unlink_refund is the undo path, nor what a successful call returns.

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?

Front-loaded with the core action and required parameters, then constraints. The amount/exclusivity sentence is dense and slightly convoluted ("amounts against one purchase or split cannot exceed it"), but no sentence is filler.

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

Completeness4/5

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

For a 4-parameter mutation tool with no output schema, the description covers preconditions, per-call semantics, and auth scope adequately. Missing only the return value / link identifier and the undo path, which are secondary since get_refund_links and unlink_refund exist as siblings.

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?

Schema coverage is 100%, so the baseline is 3; the description adds relational meaning beyond the schema by explaining that originalTxId is the transaction being refunded and refundTxId the refund itself, plus the cross-call amount semantics. It omits the schema's notable allowance of null for originalTxId (standalone refund), leaving a small mismatch in expectations.

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?

"Mark an existing transaction as a refund of another transaction" states a specific verb (mark/link) and resource (refund link) and names the two required identifiers, which cleanly separates it from siblings such as link_transfer, split_transaction, and unlink_refund.

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?

Gives concrete usage context: the two transactions must be of opposite types, an optional split can be targeted, and a single refund covering several purchases requires one call per purchase with an amount. It does not explicitly contrast with unlink_refund or link_transfer, so the agent must infer the boundary from sibling names.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.