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

TableJSON 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

TableJSON 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.

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?

Despite annotations already covering safety (idempotent, non-destructive), the description adds substantial behavior beyond them: the empty-fetch safeguard that preserves existing balances and returns status=no_change, the no_change composition retention, plus linkage semantics for linked_addresses and xpub-linked scans. This is exactly the mutation/edge-case context annotations cannot express.

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?

The purpose is correctly front-loaded, but the body then enumerates many response fields (xpub_linked, full_wallet_hint, transparent_only_hint, liquid_usd/staked_usd) that duplicate the output schema, making it dense and longer than needed. The conditional hints are operationally useful but the field enumeration could be trimmed.

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 single-parameter refresh tool with rich downstream interpretation, the description covers the critical failure modes an agent would otherwise get wrong: zero-balance privacy addresses, BTC/ZEC/DOGE full-wallet vs transparent-only cases, and staked-vs-liquid value. Nothing essential to correct handling 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?

Only one parameter (wallet_id) exists and schema coverage is 100%, including the 'do not show this ID to the user' guidance. The description adds nothing about the parameter, so the baseline 3 applies — the schema carries the load entirely.

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 opening sentence names a specific verb (re-fetch/update) and resource (on-chain asset balances for an existing wallet) plus the downstream purpose (Proof of Funds ceiling). An agent can distinguish this from get_wallet_summary (read-only view) and refresh_wallet_verification without inspecting schemas.

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?

It gives an explicit trigger: 'Use when the user says their balance looks stale, wrong, or zero after a recent on-chain change.' That is clear context for invocation, but it never names the nearest alternative (refresh_wallet_verification) or states when-not-to-use this tool, so it falls 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.

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.