mcp-server

refresh_wallet_balance

Idempotent

Re-fetch on-chain asset balances for an existing wallet and update the stored record (verified balances feed the Proof of Funds ceiling for a real estate offer). Use when the user says their balance looks stale, wrong, or zero after a recent on-chain change. Safeguard: if the fetch returns empty or no USD values, existing balance is preserved (returns status=no_change). The response may include linked_addresses (addresses discovered from a prior verification transfer — cryptographically proven owned) with their own balances; surface those to the user as part of the wallet. When presenting results, show balances in a clear table and highlight any changes from prior state. ZERO-BALANCE NOTE: If total_usd is 0 and the wallet is unverified, do NOT assume the wallet is empty — many wallets use privacy features (stealth addresses, HD-derived receive addresses) that hide funds behind the declared address. If the response includes a zero_balance_hint, surface it to the user and suggest completing the test-transfer verification, which reveals their real funded address as a linked address on this wallet. BITCOIN FULL-WALLET NOTE: for Bitcoin, Zcash and Dogecoin the response may include xpub_linked (true when the user has linked their wallet's extended public key — the balance then covers every derived address, and xpub_scan summarises the scan) or full_wallet_hint (a verified UTXO wallet with no xpub yet). When full_wallet_hint is present and the user thinks the balance is low, relay the hint and offer link_wallet_xpub. ZCASH: transparent_only_hint means only transparent (t1…) balances count — shielded ZEC is invisible and must be moved to a t-address first. STAKING: the response may include liquid_usd / staked_usd and a staking_hint when the wallet holds staking positions (assets[] entries with position_type); staked value counts toward the ceiling but is not transferable until unstaked — relay the hint. A no_change response keeps the previously stored composition.

Input Schema

Name	Required	Description	Default
`wallet_id`	Yes	Internal wallet UUID from a prior get_wallet_summary or add_wallet response. Do NOT show this ID to the user or ask them for it — look it up from the address they mentioned.

Output Schema

Name	Required	Description
`assets`	No	Per-asset balances on the wallet
`status`	Yes	refreshed \| no_change
`address`	No
`message`	No
`total_usd`	No
`wallet_id`	No
`xpub_scan`	No	Bitcoin/Zcash/Dogecoin: summary of the last extended-key scan (script_type, total_btc — native units of that coin —, total_usd, funded_address_count, scanned_at)
`blockchain`	No
`liquid_usd`	No	Eligible value transferable today (present when the wallet holds staking positions)
`staked_usd`	No	Eligible value held in staking positions — counts toward the ceiling but must be unstaked before it can be sent
`xpub_linked`	No	Bitcoin only: true when an extended public key is linked and the balance covers every derived address
`staking_hint`	No
`claimable_usd`	No
`unstaking_usd`	No
`full_wallet_hint`	No	Bitcoin/Zcash/Dogecoin: present for verified wallets with no extended key linked — how to count the full wallet via link_wallet_xpub
`linked_addresses`	No	Additional addresses proven owned via a prior verification transfer
`zero_balance_hint`	No	Surfaced when balance is 0 and the wallet is unverified — explains stealth/HD addressing
`transparent_only_hint`	No	Zcash only: only transparent (t1…) balances are verified and counted; shielded ZEC must be moved to a t-address first

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedOct 26, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```
changedOutput schema / properties / assets / items / additionalProperties
```
Previous value: -trueNew value: +{}
```
changedOutput schema / properties / linked_addresses / items / additionalProperties
```
Previous value: -trueNew value: +{}
```

changedOutput schema / properties / xpub_scan / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "properties": {},
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {},
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Changed5 schema fields changedSep 8, 2026

addedOutput schema / properties / claimable_usd

Added value: +{
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedOutput schema / properties / liquid_usd

Added value: +{
+  "description": "Eligible value transferable today (present when the wallet holds staking positions)",
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedOutput schema / properties / staked_usd

Added value: +{
+  "description": "Eligible value held in staking positions — counts toward the ceiling but must be unstaked before it can be sent",
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedOutput schema / properties / staking_hint

Added value: +{
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / unstaking_usd

Added value: +{
+  "type": [
+    "number",
+    "null"
+  ]
+}

Changed2 schema fields changedSep 6, 2026

changedOutput schema / properties / full_wallet_hint / description

Previous value: -"Bitcoin/Zcash: present for verified wallets with no extended key linked — how to count the full wallet via link_wallet_xpub"New value: +"Bitcoin/Zcash/Dogecoin: present for verified wallets with no extended key linked — how to count the full wallet via link_wallet_xpub"

changedOutput schema / properties / xpub_scan / description

Previous value: -"Bitcoin only: summary of the last extended-key scan (script_type, total_btc, total_usd, funded_address_count, scanned_at)"New value: +"Bitcoin/Zcash/Dogecoin: summary of the last extended-key scan (script_type, total_btc — native units of that coin —, total_usd, funded_address_count, scanned_at)"

Changed2 schema fields changedSep 5, 2026

changedOutput schema / properties / full_wallet_hint / description

Previous value: -"Bitcoin only: present for verified wallets with no extended key linked — how to count the full wallet via link_wallet_xpub"New value: +"Bitcoin/Zcash: present for verified wallets with no extended key linked — how to count the full wallet via link_wallet_xpub"

addedOutput schema / properties / transparent_only_hint

Added value: +{
+  "description": "Zcash only: only transparent (t1…) balances are verified and counted; shielded ZEC must be moved to a t-address first",
+  "type": [
+    "string",
+    "null"
+  ]
+}

Changed3 schema fields changedSep 4, 2026

addedOutput schema / properties / full_wallet_hint

Added value: +{
+  "description": "Bitcoin only: present for verified wallets with no extended key linked — how to count the full wallet via link_wallet_xpub",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / xpub_linked

Added value: +{
+  "description": "Bitcoin only: true when an extended public key is linked and the balance covers every derived address",
+  "type": "boolean"
+}

addedOutput schema / properties / xpub_scan

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "properties": {},
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Bitcoin only: summary of the last extended-key scan (script_type, total_btc, total_usd, funded_address_count, scanned_at)"
+}

Changed1 schema field changedMay 9, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "address": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "assets": {
+      "description": "Per-asset balances on the wallet",
+      "items": {
+        "additionalProperties": true,
+        "properties": {},
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "blockchain": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "linked_addresses": {
+      "description": "Additional addresses proven owned via a prior verification transfer",
+      "items": {
+        "additionalProperties": true,
+        "properties": {},
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "message": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "status": {
+      "description": "refreshed | no_change",
+      "type": "string"
+    },
+    "total_usd": {
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "wallet_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "zero_balance_hint": {
+      "description": "Surfaced when balance is 0 and the wallet is unverified — explains stealth/HD addressing",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "status"
+  ],
+  "type": "object"
+}

AddedApr 15, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Annotations only say non-read-only, idempotent, non-destructive, open-world; the description adds the real behavioral traits: the empty-fetch safeguard that preserves stored balances and returns status=no_change, plus conditional response branches (zero_balance_hint, xpub_linked/full_wallet_hint, transparent_only_hint, staking_hint). Idempotency and non-destructiveness are consistently reinforced by the 'no_change keeps the previously stored composition' statement.

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

Conciseness3/5

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

Purpose and trigger are front-loaded, which is good, but the bulk is a stacked run of ALL-CAPS response-handling notes (ZERO-BALANCE, BITCOIN FULL-WALLET, ZCASH, STAKING) that partly duplicate what an output schema already conveys. Roughly a third of the text could move to output-schema documentation without losing agent-critical guidance.

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 write-back refresh tool with an output schema present, the description covers everything an agent needs to call and then interpret it: the safeguard, linked_addresses, the zero-balance false-negative trap, xpub/full-wallet handling, shielded ZEC, and staking vs. liquid value. Nothing operationally material is missing.

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?

Single parameter with 100% schema coverage; the schema already explains that wallet_id is an internal UUID from get_wallet_summary/add_wallet that must not be shown to the user. The description adds no further parameter-level meaning, so the baseline of 3 applies.

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: 'Re-fetch on-chain asset balances for an existing wallet and update the stored record.' It also scopes the business meaning (balances feed the Proof of Funds ceiling), which separates it from get_wallet_summary (read) and refresh_wallet_verification (verification state).

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?

'Use when the user says their balance looks stale, wrong, or zero after a recent on-chain change' gives a concrete trigger condition. It also routes follow-on cases to siblings (link_wallet_xpub, test-transfer verification), though it never explicitly contrasts with the plain read path (get_wallet_summary) or refresh_wallet_verification.

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

All mcp-server tools Inspect

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.