Skip to main content
Glama

mcp-server

by io.github.realopengroup
OverviewDiscussionsAdmin

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
NameRequiredDescriptionDefault
wallet_idYesInternal 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
NameRequiredDescriptionDefault
assetsNoPer-asset balances on the wallet
statusYesrefreshed | no_change
addressNo
messageNo
total_usdNo
wallet_idNo
xpub_scanNoBitcoin/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)
blockchainNo
liquid_usdNoEligible value transferable today (present when the wallet holds staking positions)
staked_usdNoEligible value held in staking positions — counts toward the ceiling but must be unstaked before it can be sent
xpub_linkedNoBitcoin only: true when an extended public key is linked and the balance covers every derived address
staking_hintNo
claimable_usdNo
unstaking_usdNo
full_wallet_hintNoBitcoin/Zcash/Dogecoin: present for verified wallets with no extended key linked — how to count the full wallet via link_wallet_xpub
linked_addressesNoAdditional addresses proven owned via a prior verification transfer
zero_balance_hintNoSurfaced when balance is 0 and the wallet is unverified — explains stealth/HD addressing
transparent_only_hintNoZcash 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.

  1. Changed5 schema fields changed
    • 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"
+  ]
+}
  2. Changed2 schema fields changed
    • 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)"
  3. Changed2 schema fields changed
    • 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"
+  ]
+}
  4. Changed3 schema fields changed
    • 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)"
+}
  5. Changed1 schema field changed
    • 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"
+}
  6. Added

TDQS

A4.3/5.0
Behavior4/5

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

Annotations indicate this is a write operation (readOnlyHint=false) and idempotent, which the description does not contradict (it states existing balance is preserved on no_change). The description goes beyond annotations by detailing edge cases: empty results preserve state, privacy features may hide funds, Bitcoin full-wallet behavior, Zcash transparent-only counting, and staking value non-transferability. It does not explicitly say it updates a record, but 'update the stored record' is present, so this is clear.

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 description is long and thorough, but it front-loads the core purpose and trigger. The many notes (zero-balance, bitcoin, zcash, staking) are necessary given the tool's complexity, but they make it dense and could be more structured with bullet points. It is arguably over-specified for an agent to parse, though every note serves a purpose.

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?

Given the tool's complexity (multiple chains, hints, and edge cases), the description covers every relevant scenario: returning no_change, linked_addresses, zero_balance_hint, xpub_linked/full_wallet_hint, transparent_only_hint, and staking hints. It also covers agent presentation guidance (table, highlights) and user interaction (relay hints). The output schema exists, so return value details are not required. This is complete for an agent.

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?

The schema already fully documents wallet_id (coverage=100%), including that it is an internal UUID and a lookup instruction. The description adds no extra syntax or semantics for the parameter, relying on the schema. This is a baseline score of 3 since the schema does the heavy lifting.

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 states the tool's purpose precisely: 'Re-fetch on-chain asset balances for an existing wallet and update the stored record' – a clear verb, resource, and effect. It explicitly ties the fetched balances to the 'Proof of Funds ceiling', establishing domain context. It also distinguishes from siblings (e.g., refresh_wallet_verification, get_wallet_summary) by focusing on balance refresh rather than verification or reading.

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?

The description gives an explicit trigger: 'Use when the user says their balance looks stale, wrong, or zero after a recent on-chain change.' It also states safeguards (no_change preserves existing balance) and instructs to relay various hints (zero_balance_hint, full_wallet_hint, staking_hint) and suggest follow-ups like link_wallet_xpub. This is a complete 'when and how' guide.

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

All mcp-server toolsInspect
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.

Resources