Skip to main content
Glama
0xfreak0

sui-analytics-mcp

by 0xfreak0
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Get balance

get_balance
Read-only

Check the spendable balance of a Sui address or object for any coin type, now or at a past time or checkpoint, including funds held without coin objects.

Instructions

Get the liquid balance of one coin type for a Sui address or object (defaults to SUI), now or at a past time or checkpoint. balance is the total the owner can spend: coin_balance is held as Coin objects and address_balance sits in the owner's address balance, which holds funds without any coin object, so a wallet with no coins can still hold a large balance. For an object id, address_balance is funds held by the object itself, which only its defining module can withdraw. Staked SUI and value locked in DeFi positions do not appear here, so a wallet that looks nearly empty may not be: pair it with get_staking_summary and get_defi_positions before concluding anything about what an address holds. For every coin at once, use get_wallet_overview. With at or at_checkpoint, a checkpoint inside GraphQL's consistent range (about the last hour) is read directly (method: consistent_read). An older one is reconstructed (method: reconstructed): the balance at a recent anchor checkpoint minus the owner's balance changes in every transaction after the requested checkpoint, which is exact when complete is true. Reconstruction reads at most max_transactions; when that runs out, complete is false, balance is null and reached_checkpoint says how far back the scan got. A reconstructed balance has no coin/address split (coin_balance and address_balance are null); anchor carries the split at the anchor checkpoint.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
atNoBalance as of this time (ISO 8601, e.g. 2025-09-07T16:00:00Z): the last checkpoint stamped at or before it. Give this or `at_checkpoint`, not both.
ownerNoOwner address (0x...). Required; `address` is accepted in its place.
addressNoAlias for `owner`.
networkNoNetwork: 'mainnet' (default) | 'testnet' | 'devnet'
coin_typeNoCoin type (default: 0x2::sui::SUI)
at_checkpointNoBalance as of the end of this checkpoint. Give this or `at`, not both.
max_transactionsNoMost transactions a reconstruction reads (default 1000, max 10000). Each page of 50 is one request. Ignored for a current or consistent-range read.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changedv1.20.0
    • addedInput schema / properties / address
      Added value: +{
+  "description": "Alias for `owner`.",
+  "type": "string"
+}
    • addedInput schema / properties / at
      Added value: +{
+  "description": "Balance as of this time (ISO 8601, e.g. 2025-09-07T16:00:00Z): the last checkpoint stamped at or before it. Give this or `at_checkpoint`, not both.",
+  "type": "string"
+}
    • changedInput schema / properties / at_checkpoint / description
      Previous value: -"Query balance at a specific checkpoint (for historical balances)"New value: +"Balance as of the end of this checkpoint. Give this or `at`, not both."
    • addedInput schema / properties / at_checkpoint / minimum
      Added value: +0
    • changedInput schema / properties / at_checkpoint / type
      Previous value: -"number"New value: +"integer"
    • addedInput schema / properties / max_transactions
      Added value: +{
+  "description": "Most transactions a reconstruction reads (default 1000, max 10000). Each page of 50 is one request. Ignored for a current or consistent-range read.",
+  "maximum": 10000,
+  "minimum": 1,
+  "type": "integer"
+}
    • changedInput schema / properties / network / description
      Previous value: -"Which Sui network to run this call against: 'mainnet' (default), 'testnet', or 'devnet'. Set this per-call — different tool calls in the same session can target different networks (e.g. to compare a value on testnet against mainnet)."New value: +"Network: 'mainnet' (default) | 'testnet' | 'devnet'"
    • changedInput schema / properties / owner / description
      Previous value: -"Owner address (0x...)"New value: +"Owner address (0x...). Required; `address` is accepted in its place."
    • removedInput schema / required
      Removed value: -[
-  "owner"
-]
  2. First observedv1.5.0

TDQS

A5/5.0
Behavior5/5

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

Annotations declare readOnlyHint and openWorldHint, and the description enriches this with detailed behavior: the distinction between coin_balance and address_balance, exclusion of staked and DeFi funds, reconstruction mechanics, null fields, and the meaning of 'complete' and 'reached_checkpoint'. No contradiction with annotations found.

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 long but every sentence carries essential information. It is well-structured, starting with the core purpose, then diving into nuances and edge cases. No filler or tautology; each clause adds value to an agent's understanding.

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 complex tool with 7 parameters and no output schema, the description covers all critical scenarios: current vs historical reads, reconstruction behavior, null cases, the meaning of anchors, and relationships to other tools. An agent has sufficient knowledge to invoke it correctly in any situation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds substantial semantics beyond the schema: it explains the effect of 'at' and 'at_checkpoint', the meaning of 'balance' vs 'coin_balance' vs 'address_balance', the max_transactions behavior and its impact on completeness, and the alias relationship between 'address' and 'owner'. This far exceeds the baseline for full schema coverage.

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 specifies the exact operation: get the liquid balance of one coin type for a Sui address or object, with a default coin (SUI). It clearly distinguishes from sibling get_wallet_overview (all coins at once) and provides context on what is excluded (staked SUI, DeFi). The purpose is unmistakable.

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?

Explicitly states when to use alternatives: 'For every coin at once, use get_wallet_overview' and 'pair it with get_staking_summary and get_defi_positions before concluding anything.' It also clarifies when reconstruction is used and its limitations, giving the agent clear decision criteria.

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

Deploy Server

Other Tools