Skip to main content
Glama

mcp-server

by io.github.realopengroup

refresh_wallet_balance

Idempotent

Re-fetch on-chain asset balances for an existing wallet and update the stored record. 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.

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
blockchainNo
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

TDQS

A4.5/5.0
Behavior5/5

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

Despite having annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds substantial behavioral context: it preserves existing balance on empty fetch (returns status=no_change), may include linked_addresses, and explains zero-balance handling for unverified wallets with privacy features. This goes well beyond what annotations provide.

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

Conciseness5/5

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

The description is lengthy but every sentence earns its place, covering use cases, safeguards, and presentation instructions. It is well-structured with clear sections and front-loads the primary action, making it efficient despite its detail.

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, the description covers edge cases (zero balance, empty fetch), output expectations (status, linked_addresses), and user-facing presentation. With an output schema present and this level of detail, the description is highly complete and self-sufficient.

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%, and the schema already provides a rich explanation for wallet_id (internal UUID, do not show to user). The description itself doesn't add parameter-specific meaning, but the baseline of 3 applies when 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 uses a specific verb ('Re-fetch') and resource ('on-chain asset balances for an existing wallet'), clearly distinguishing it from siblings like refresh_wallet_verification and get_wallet_summary. It also explicitly states the action updates the stored record, making the tool's purpose unmistakable.

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?

The description explicitly provides a when-to-use trigger: 'Use when the user says their balance looks stale, wrong, or zero after a recent on-chain change.' It lacks explicit when-not-to-use or alternative tool names, but the context is strong enough to guide correct selection.

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
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0
Disambiguation4/5

Most tools have clearly distinct purposes (wallet management, verification, knowledge lookup, marketing, account status), but there is minor overlap between add_wallet and refresh_wallet_verification (both generate verification challenges) and between get_started and get_account_status (both touch on next-step resolution). Descriptions clarify the differences, so confusion is unlikely.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (e.g., add_wallet, get_wallet_summary, verify_wallet_transfer), with only 'logout' as a single verb, which is still consistent with the imperative style. No mixed conventions or cryptic names.

Tool Count4/5

The server exposes 20 tools, which is on the heavier side of the typical range but appropriate for the broad domain (wallet operations, verification, KYC, knowledge base, marketing assets, referral tracking). Each tool has a distinct role, so the count feels justified rather than bloated.

Completeness5/5

The surface covers the full lifecycle for crypto-to-real-estate transactions: wallet management (add, remove, refresh, verify), identity verification, proof-of-funds generation, knowledge tools (fees, coverage, supported crypto, how-it-works), marketing (snippets, assets, referral), and account navigation (get_started, logout). No obvious gaps that would leave an agent stuck.

Resources