Skip to main content
Glama

Report your own-wallet claim

reveal_claim
DestructiveIdempotent

Reports the revealed HTLC secret and claim transaction after you claim your leg on-chain, enabling the counterparty and watchers to settle the other leg.

Instructions

After you claimed your receive leg on-chain with your OWN wallet (secret from get_deal_secret), report the revealed secret + claim tx so the counterparty and watchers can settle the other leg. Not needed after claim_leg, which reports its own claim. Your own secret goes through the same gate as get_deal_secret first.

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": {
      "swap_id": "<swap_id>",
      "secret": "<secret>"
    },
    "name": "reveal_claim"
  }
}

Input Schema

NameRequiredDescriptionDefault
legNoOptional; if given, the leg you claimed — the one that pays you
secretYes64-char hex preimage (from get_deal_secret or the on-chain claim)
swap_idYesSwap id (swap.id from deal_status, or swapId once a deal is agreed)
claim_txNoHash of your claim transaction

Output Schema

NameRequiredDescriptionDefault
idNoSwap id
errorNoSet instead when the call failed
statusNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv1.11.1
    • removedInput schema / additionalProperties
      Removed value: -false
    • addedInput schema / properties / claim_tx / description
      Added value: +"Hash of your claim transaction"
    • addedInput schema / properties / leg / description
      Added value: +"Optional; if given, the leg you claimed — the one that pays you"
    • addedInput schema / properties / swap_id / description
      Added value: +"Swap id (swap.id from deal_status, or swapId once a deal is agreed)"
    • addedInput schema / properties / swap_id / pattern
      Added 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)$"
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": {},
      +  "properties": {
      +    "error": {
      +      "additionalProperties": {},
      +      "description": "Set instead when the call failed",
      +      "properties": {
      +        "code": {
      +          "type": "string"
      +        },
      +        "is_retryable": {
      +          "type": "boolean"
      +        },
      +        "message": {
      +          "type": "string"
      +        },
      +        "recovery_hint": {
      +          "type": "string"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "id": {
      +      "description": "Swap id",
      +      "type": "string"
      +    },
      +    "status": {
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
  2. Addedv0.10.0

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description is not carrying the whole load, but it does explain why disclosure matters (the counterparty and watchers use the secret to settle the other leg) and that the secret passes through the same gate as get_deal_secret. That is real behavioral context beyond the structured fields, though the idempotency and re-submission behavior are left to the annotations.

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?

Three tightly packed sentences with the trigger condition front-loaded and no filler. The phrase 'same gate as get_deal_secret' is slightly compressed jargon, but it conveys a prerequisite that would otherwise cost a sentence.

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?

An output schema exists, so return values need not be described, and the description covers trigger, exclusion, prior step, and secret provenance. What remains unstated is whether re-reporting is safe and whether the counterparty is notified synchronously, which matters mildly given the destructive hint.

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?

Schema description coverage is 100%, so the baseline is 3 and the input schema already explains every field, including the 64-char hex format and the uuid source for swap_id. The description adds the provenance of the secret and clarifies that the leg is 'the one that pays you', but contributes little else beyond the schema.

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 names a specific action (report the revealed secret plus claim tx) on a specific resource and states the precondition that selects it (you already claimed your receive leg on-chain with your OWN wallet). It also explicitly separates itself from the nearest sibling, claim_leg, which reports its own claim.

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?

Both the when and the when-not are given: use it after an own-wallet on-chain claim, and it is explicitly not needed after claim_leg. The dependency on get_deal_secret as the secret source is stated, so an agent can sequence the calls without inference.

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