Skip to main content
Glama

Claim your leg

claim_leg
Destructive

Claims the receiving leg of an HTLC swap using the agent's key and preimage, reveals the secret on-chain so the counterparty can settle the other leg, and reports the claim to the API.

Instructions

AUTONOMOUS SETTLEMENT: claim YOUR receive leg of a swap using the preimage, signing with the agent's own key. This reveals the secret on-chain (so the counterparty/keeper can settle the other leg) and reports the claim to the API. Requires both legs funded and the preimage available (you are the initiator, or the initiator already revealed it). As the initiator it first checks the counterparty's escrow on chain (pays your key, agreed terms, still claimable) and refuses otherwise. Use this when the agent holds the receiving key; to claim with your own wallet use get_deal_secret, then reveal_claim. Returns the on-chain tx id.

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>"
    },
    "name": "claim_leg"
  }
}

Input Schema

NameRequiredDescriptionDefault
swap_idYesSwap id (swap.id from deal_status, or swapId once a deal is agreed)

Output Schema

NameRequiredDescriptionDefault
txNoOn-chain tx id
legNo
chainNo
errorNoSet instead when the call failed

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv1.11.1
    • removedInput schema / additionalProperties
      Removed value: -false
    • 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": {
      +    "chain": {
      +      "type": "string"
      +    },
      +    "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"
      +    },
      +    "leg": {
      +      "type": "string"
      +    },
      +    "tx": {
      +      "description": "On-chain tx id",
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
  2. Addedv0.10.0

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations by disclosing the irreversible side effect (the secret is revealed on-chain so the counterparty can settle), the API reporting step, and the pre-flight escrow check that can cause refusal. That is exactly the kind of consequence and failure-mode detail destructiveHint alone cannot convey.

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?

The critical trait (autonomous settlement, secret revealed) is front-loaded and every sentence carries distinct information. It is dense with parentheticals and a capitalized banner, which makes it slightly harder to scan than it needs to be.

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?

For a destructive, open-world, non-idempotent mutation, the description covers preconditions, alternatives, side effects and the check that may reject the call; the return value is already covered by the output schema.

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?

Only one parameter and the schema documents it at 100% coverage, so the description's silence on swap_id formatting costs nothing. Baseline 3 applies since no additional meaning is added 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?

States a specific verb and resource ('claim YOUR receive leg of a swap using the preimage') plus the mechanism ('signing with the agent's own key'), which immediately separates it from the sibling reveal_claim and get_deal_secret paths.

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?

Gives explicit selection criteria ('Use this when the agent holds the receiving key') and names the alternative workflow ('to claim with your own wallet use get_deal_secret, then reveal_claim'), including the required state (both legs funded, preimage available, initiator status).

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