A read-only MCP server for investigating activity on Sui, giving Claude 67 tools to trace funds, attribute wallets, inspect tokens, packages, DeFi positions and NFTs — with no wallet or keys required.
Wallet & chain lookups — identify addresses, get wallet overviews (balances, SuiNS, staking, kiosks), fetch transactions, objects, chain info, checkpoints and SuiNS names.
Token analysis — metadata, current and historical USD prices, top holders, holder rankings, and verified-vs-impostor coin checks.
DeFi & NFTs — positions across Suilend, Cetus, NAVI, Scallop, Bluefin and Bucket; find pools; DeepBook order book, trades and oracle-vs-market comparison; list NFTs and collections with kiosk-aware ownership.
Fund tracing & forensics — multi-hop USD-valued fund tracing, funding-source attribution in batches, address fan-out, wallet-edge clustering, bridge transfer resolution, address labels, timelines, object provenance and live address watching.
Multisig analysis — read a wallet's committee from its address, see which keys are live or dormant, who signed a given transaction, and derive shared multisigs from suspect addresses.
Move package analysis — disassembly, decompilation (optional external binary), risk scans, capability/publisher attribution, upgrade diffing, dependency graphs, PTB decoding and MVR name resolution.
Transaction building — build unsigned transfers and staking transactions, and dry-run them without ever submitting or holding keys.
Case management — record, list, export and delete findings across sessions, with optional local SQLite storage and tool profiles loadable at runtime via enable_tools.
Provides tools for Sui blockchain analytics, including wallet overviews, DeFi positions, NFTs, token prices, transaction decoding, fund tracing, pool discovery, staking, Move bytecode decompilation, and Move Registry name resolution.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@sui-analytics-mcp show me my latest transactions"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Read-only MCP server for investigating activity on Sui. Trace where funds went, attribute wallets to their funding sources, rank addresses by protocol flow, work out who can actually sign for a multisig treasury, and tell a coordinated cluster from a crowd, then reconstruct it all on a timeline.
67 tools. It also covers the ordinary things: wallet overviews, DeFi positions, NFTs, prices and Move package analysis.
Add this to your MCP client config (Claude Code, Claude Desktop, Cursor, or anything else that speaks MCP over stdio):
{
"mcpServers": {
"sui": {
"command": "npx",
"args": ["-y", "sui-analytics-mcp"]
}
}
}No account, API key, or config file is required. The server reads public Sui endpoints and defaults to mainnet. Requires Node.js >= 22.13.
Doing investigative work? Start with the forensics tools loaded:
"env": { "SUI_TOOLS": "core,forensics" }Related MCP server: Sui MCP Server
Ranking a lending protocol's wallets for a day, then testing whether a cluster is coordinated, in six calls:
aggregate_events(module: <package>, from: "2026-08-07T00:00:00Z", to: "now")
→ every event type it emits, with counts and the numeric fields available
(user actions are usually far rarer than bookkeeping events)
aggregate_events(event_type: <DepositEvent>, value_field: "event.deposit_value", value_scale: 100)
→ wallets ranked by USD deposited, truncated: false
find_funding_sources(addresses: [...25], depth: "first_hop")
→ 23 of 25 share one funder, funded in three bursts of under a minute
get_address_fanout(<that funder>)
→ 1,623 recipients, classified "distributor", so shared funding alone
proves nothing here; the second-level timing clusters carry the caseSeveral wallets tracing back to one funder looks decisive until you measure the funder itself. A distributor with 1,623 recipients funds unrelated wallets all day, so shared funding on its own says very little. Every funding result includes the fan-out measurement for this reason.
Fan-out reports shape as well as size. Measured on the same day, a known exchange and a sybil funder had almost identical counterparty counts, 399 and 431, but very different flow. The exchange ran balanced at 0.73 out/in, deposits in and withdrawals out. The funder ran 9.78, paying many addresses and being paid by few.
A Sui address is the hash of whatever authenticates it. For a multisig, the threshold, every member key and every weight are part of that hash, so the committee can be read off the address and checked by deriving it and confirming it reproduces the address.
Identify a wallet and its committee. identify_address returns the shape, every member address, and each member resolved to its own name, labels and SuiNS history.
identify_address(0x045dadba…)
→ authentication: multisig, 4-of-7, verified: true
committee_members: 7, each with name/label/kindSee which keys are actually used. The committee never changes, but who signs varies per transaction. analyze_multisig reads that across the wallet's history.
analyze_multisig(0x045dadba…, max_transactions: 200)
→ transactions_examined: 8
signer_sets: [0,1,3,4] x4, [1,2,3,4] x2, [0,2,3,4] x2
always_present: [3, 4]
dormant_members: [5, 6]
active_signers_meet_threshold: truedormant_members are keys that hold weight and have never used it. always_present are keys the wallet currently cannot move without. Both are reported against transactions_examined, since the claim is only as good as the window.
See who authorised one transaction. get_transaction returns an authorization block naming the keys that signed and the members that did not, plus the gas sponsor when there is one.
get_transaction(oxrJ3Bppuk…)
→ authorization[0]: sender, multisig 4-of-7
signed_by: [0, 1, 3, 4]
did_not_sign: [2, 5, 6]Search backwards from keys to a treasury. Given addresses a trace has already linked, find_shared_multisig derives every committee they could form and returns the ones that exist on chain. This finds multisigs that never appeared in the trace, since a wallet is only visible if it transacted with something you looked at.
find_shared_multisig([0xafe2fafa…, 0xc848c5cc…])
→ candidates_checked: 4, found: 1
0xcf4e7b88… 1-of-2, evidence_tier: chain-derivedClustering. build_wallet_edges emits a co_signer edge for any key that can spend a wallet on its own, and marks clusters built only from those chain-derived rather than heuristic. Keys sitting on more committees than the limit are treated as custody or wallet-provider keys and listed under excluded_co_signers instead of linking everyone who uses that provider.
Limits, also stated in the tool output. Member order is part of the address, so find_shared_multisig is factorial in committee size and refuses past five keys; it covers equal-weight committees only, so a nil result is not a negative finding. A wallet that has never sent a transaction cannot be classified at all, because it has produced no signature. It comes back as unknown rather than as an ordinary wallet.
zkLogin and passkey wallets go through the same path. zkLogin reports its OAuth issuer, which is all the chain discloses about the account.
Several tools qualify their own answers rather than returning a number that looks more certain than it is.
Is this coin the one you meant? A symbol is not an identifier on Sui. 8,008
mainnet coins share one with another, and imitators are named to be mistaken.
analyze_token reports verified, and every balance change in a trace carries
coin_verified:
-850 MAGMA (unverified, assumed scale) coin_verified=false
+202.361728 USDC coin_verified=trueThese are two separate marks. unverified refers to which coin it is.
assumed scale refers to whether the amount is right: decimals for an unknown
coin are a guess, and 47 of 289 imitators declare a different scale from the
coin they imitate.
An ambiguous symbol returns candidates rather than a coin. USDC matches seven
legitimate verified coins on Sui (Circle's, Wormhole's, Celer's), so picking one
would misreport which asset moved.
Why did it fail? get_transaction returns the abort code with the package,
module and function that raised it, and a clever error's constant name where the
author defined one.
Who deployed this, and can they still change it? analyze_package and
identify_address report publisher, the address that created the package,
attributed to the lineage root. The UpgradeCap carries holder_status:
burned means upgrade rights were renounced, which reduces risk, and is what
27 of every 30 departing caps did.
Has an issuer frozen this address? check_coin_restrictions reads the
on-chain deny list in both directions. A frozen address usually holds none of
the coin that froze it, so it checks every configured coin type rather than the
ones it holds.
What moved that was not a coin? trace_funds reports object_flow.
Sui is object-based, so a balance change only covers Coin<T>. An NFT, a
Kiosk or a capability changes hands without producing one:
--- Hop 1 (2025-01-10 10:25:31 UTC) ---
Sender: 0x8c4f…5ee8
Action: Transfer to recipient
Objects:
package::UpgradeCap ⚠ 0x8c4f…5ee8 -> 0xeda2…6c2b
Whoever holds this can publish new code for the package.Kiosk moves are included. A kiosk-held NFT is owned by the Kiosk object, so an
ordinary NFT trade reads object -> object, and that counts as a custody
change. DeFi position objects are named by their protocol, for example
position::Position (Cetus).
Transfers of UpgradeCap, TreasuryCap, DenyCap, DenyCapV2 and
Publisher are marked as carrying control. A capability sent to an unspendable
address is reported under renounced_capabilities instead, since those rights
have been given up rather than transferred.
What has happened since I last looked? watch_addresses records a set of
addresses and where it last looked; poll_watch returns only what is new:
{ "watched": 20, "active": 0, "hits": [], "requests": 1 }That empty answer is 13 tokens and one request, so it is cheap to call
repeatedly. Nothing triggers a poll on its own; the caller drives it. A hit
names the address, digest, checkpoint and why it fired. It does not include the
transaction, which you read separately with get_transaction:
reason | |
| coin moved, with per-coin nets |
| mint, upgrade, freeze or publish rights changed hands |
| an NFT, kiosk item or DeFi position changed hands |
| a counterparty carries a sink label |
| a new counterparty renders like a watched address |
| something happened that moved no coin and no named object |
Watching starts from the current checkpoint, so adding an address does not
replay its history. min_amount filters coin movements only: a labelled sink
or a transfer that moves no coin is reported whatever its size. An address busy
enough to fill the per-poll cap is listed in more_pending rather than being
silently truncated. Requires SUI_STORE_PATH.
Are these really the top holders? Only when complete_ranking is true.
get_top_holders walks coin objects in object-id order, which is unrelated to
balance. A scan that stops early returns the largest holder it happened to see.
On SUI the reported top holder goes from 66 SUI at max_scan 200 to 3,454 at
800, with no overlap in the top five. A truncated scan therefore returns
sampled_holders, without a rank or a percentage of supply, along with a
caveat. Raise max_scan until truncated is false to get a real ranking; that
is only practical for coins with few enough objects to enumerate.
analyze_token reports the same distinction.
Is this address the one it looks like? get_transaction_history and
trace_funds compare every address they touch and report address_poisoning
when two of them are close enough to be mistaken for one another:
⚠ Addresses in this trace close enough to be mistaken for one another:
0xd649a4d5…57127127 vs 0xd642ef27…c75d7127An attacker generates an address sharing the leading and trailing characters of one you already deal with, sends dust from it, and waits for someone to copy the wrong row out of their own history. The check covers senders, balance-change recipients and the branches a trace declined to follow. A poisoning wallet sends rather than receives, so it never shows up as a counterparty, and the lookalike is usually several hops from the address it imitates.
A pair is reported when at least three characters match at each end, roughly one collision in seventeen million pairs by chance. The two addresses do not render identically at every width; they match at both ends, which is enough to fool a glance or a short truncation.
The address with the larger footprint is named as the established side, but only
when the gap is wide enough to support it. Dust repeating inside a single page
is normal for this attack, so a small margin proves nothing. Below that, the
pair is reported with direction_known: false.
Does this address pay other people's gas? get_address_fanout reports
sponsor_shape. This is invisible to value fan-out, since sponsoring moves
none of the sponsor's own money. relayer is proven; private_sponsor off a
truncated scan is flagged provisional, since breadth only grows with the
window.
The server gives Claude chain access, but not method: which tool answers which question, what a control group is for, and which conclusions to refuse. That lives in a skill shipped alongside it.
mkdir -p ~/.claude/skills
cp -r "$(npm root -g)/sui-analytics-mcp/.claude/skills/sui-forensics" ~/.claude/skills/Or copy .claude/skills/sui-forensics/ out of this repo. It loads automatically
once present; there is nothing to configure.
It covers the evidence tiers and what each one lets you claim, the order to work in, the base-rate check that keeps shared ancestry from reading as collusion, and the conclusions to refuse. "No edge found, so they are unrelated" is the most common of those.
All 67 tools loaded at once cost about 14k tokens of context on every request, and a large flat tool list makes models pick the wrong tool. So the server starts with a core set of 17 and keeps the rest one call away.
When you ask for something outside the current set, such as "trace where these funds went", the model calls enable_tools and the tracing tools appear immediately, with no restart. You never have to pick a profile.
To start with more, set SUI_TOOLS:
"env": { "SUI_TOOLS": "core,forensics" }Profile | Tools | Contents |
| 18 | Wallets, balances, transactions (single and batched), tokens, NFTs, DeFi positions, staking, pools, names |
| 29 | Fund tracing, funding-source attribution, cross-chain bridge resolution, wallet-edge clustering, package analysis, control-group sampling, timelines, object provenance, labels, events, oracle-vs-market deviation, live address watching |
| 18 | Move packages, disassembly, decompilation, upgrade diffing, dependency graphs, PTB decoding, unsigned transaction building, Move Registry |
| 6 | DeepBook order book and fills, pool stats, token search, validators |
| 59 | Everything |
Runtime switching relies on notifications/tools/list_changed. Claude Code and Claude Desktop honour it; some clients cache the tool list and will only see the change after a restart. SUI_TOOLS always works, so set it explicitly if your client doesn't refresh.
Upgrading from 1.1.x, where every tool loaded at startup? Set SUI_TOOLS=all to keep that behaviour.
The server has no credentials and no ability to move funds:
It never accepts a private key, mnemonic, or seed phrase. No tool takes one as an argument and nothing in the code reads one from the environment.
It never submits a transaction. build_transfer and build_staking return unsigned BCS bytes that you sign and broadcast somewhere else; simulate_transaction dry-runs bytes against a fullnode without executing them.
Every remaining tool is a read.
No provider accounts. RPC, indexing, and price data all come from public endpoints.
Supply-chain scanners report which capabilities a package uses but not why. The full list for this one:
Capability | Where it's used |
Network | Public Sui RPC and GraphQL, plus Pyth, Aftermath and the Move Registry for prices and name resolution. Hosts are listed in |
Filesystem | Temp files for |
Subprocess | One call, in |
Environment | The |
There is no eval, no dynamic require, no minified or obfuscated code, and no telemetry. Inputs that come from the chain are treated as untrusted: decompile_module validates module names before they reach a filesystem path, and bounds how many modules one call will process.
Most of the dependency tree is the MCP SDK. This server speaks stdio only and imports just server/mcp.js and server/stdio.js, so the SDK's HTTP-transport dependencies are installed but never loaded.
Releases are published from CI with npm provenance, so every tarball carries a signed attestation tying it to the commit and workflow run that produced it:
npm audit signaturesPer-call network — every tool takes an optional network arg (mainnet / testnet / devnet); query multiple networks in one session (e.g. compare a testnet value to mainnet). SUI_NETWORK sets only the default.
Protocol-aware — decodes transactions from Cetus, Suilend, NAVI, Scallop, Bluefin, DeepBook, and more into human-readable actions
Incident investigation — labeled fund tracing, batch funding attribution with fan-out controls, multi-address timelines, object provenance, PTB anomaly triage, oracle-vs-market deviation
Multisig — a Sui address is the hash of its authenticator, so the committee is read off the address itself. Names every member, says which keys are live and which have never signed, and shows who signed a given transaction. Also handles zkLogin and passkey wallets
Move package analysis — disassembly, heuristic risk scan, capability audit, publisher attribution, upgrade-cap holder status, and upgrade diffing, none of which need an external binary
Asset verification — a curated coin registry, so a trace says whether the asset it followed is the real one rather than an imitator wearing its symbol
Multi-source architecture — gRPC for low-latency reads, GraphQL for filtered queries, archive node fallback for historical data
Price aggregation — Aftermath Finance, Pyth oracles, and CoinGecko in a single unified interface
Kiosk-aware — resolves NFT ownership through Sui's kiosk system to actual wallet addresses
Move Registry (MVR) — resolves names like @deepbook/core to package addresses, and back
All environment variables are optional. See .env.example for the full list; the common ones are SUI_NETWORK (default network), SUI_FULLNODE_URL / SUI_GRAPHQL_URL (custom RPC endpoints), and SUI_LABELS_FILE (address attribution labels for fund tracing).
Current USD prices come from Aftermath, which is free and needs no key. That is the default path, and it covers everything except historical pricing.
Two paid sources are opt-in and engage only when their key is set, so nobody is billed by accident and nothing degrades if you set neither:
Variable | Enables |
| Historical prices ( |
| CoinMarketCap as an additional current-price source. Note it keys on ticker symbols, which are not unique on-chain, so it is only consulted for symbols already mapped to a coin type. |
Without a key, tools that need a paid source say so explicitly rather than returning a null price. A missing price and a price of zero mean different things.
Set SUI_STORE_PATH to keep address labels and fan-out measurements across sessions. It uses Node's built-in node:sqlite, so it adds no dependency and no native build. It is unset by default, and nothing is written to disk unless you set it. An investigation store is a record of which addresses you looked at, so that default is deliberate.
"env": { "SUI_STORE_PATH": "/Users/you/.local/share/sui-mcp/store.db" }Fund traces are not cached. A trace depends on your label set, so a stored result would disagree with a fresh run as soon as a label changed.
{
"mcpServers": {
"sui": {
"command": "npx",
"args": ["-y", "sui-analytics-mcp"],
"env": { "SUI_NETWORK": "testnet" }
}
}
}64 of the 67 tools need nothing beyond the install above. Only decompile_module requires an external binary, and there are lighter options to try first:
disassemble_module returns Move bytecode assembly via the GraphQL endpoint.
analyze_package summarizes a package's API and runs a heuristic risk scan.
diff_package_upgrade diffs two versions of a package.
Use the decompiler when you want higher-level, source-like Move output instead of bytecode.
The binary is Revela's move-decompiler, built from Rust. It is not bundled in the npm package because a published tarball could only carry one platform's build, so you compile it once yourself and point the server at it with SUI_DECOMPILER_PATH. This works the same whether you installed via npx or from source. You need a Rust toolchain (rustup.rs); the build takes a few minutes.
git clone --depth 1 https://github.com/verichains/revela_sui.git
cd revela_sui/external-crates/move
cargo build --release --bin move-decompiler
# binary lands at target/release/move-decompilerThen add its absolute path to your client config:
{
"mcpServers": {
"sui": {
"command": "npx",
"args": ["-y", "sui-analytics-mcp"],
"env": {
"SUI_DECOMPILER_PATH": "/absolute/path/to/revela_sui/external-crates/move/target/release/move-decompiler"
}
}
}
}If you already cloned this repo, npm run build:decompiler does the same clone and build and copies the result to bin/move-decompiler.
Without SUI_DECOMPILER_PATH the server falls back to looking for move-decompiler on PATH. Prefer the absolute path: desktop clients often launch servers with a minimal environment that doesn't include your shell's PATH, so a binary you can run in a terminal may still be invisible to the server. If it's found in neither place, decompile_module returns an error explaining how to fix it, and the other 56 tools are unaffected.
For development, or to run a version you've modified:
git clone https://github.com/0xfreak0/sui-mcp.git
cd sui-mcp
npm install
npm run buildThen point your client at the build output instead of npx:
{
"mcpServers": {
"sui": {
"command": "node",
"args": ["/absolute/path/to/sui-mcp/dist/index.js"]
}
}
}See CONTRIBUTING.md for the development and release workflow.
Tool | Description |
| Identify what a Sui address is: wallet, package, validator, or object |
| Comprehensive wallet overview: balances, SuiNS name, staking, kiosks, recent txs |
| Decoded activity feed with protocol names and human-readable actions |
| Full token analysis: metadata, price, 24h change, supply, top holders |
Tool | Description |
| Current chain ID, epoch, checkpoint height, timestamp, gas price |
| Checkpoint details by sequence number or digest |
Tool | Description |
| Object by ID with type, owner, JSON content, and display metadata |
| List objects owned by an address with optional type filter |
| Dynamic fields of an object (tables, kiosk contents, etc.) |
Tool | Description |
| Balance of a coin type for an address (defaults to SUI) |
| Token metadata: name, symbol, decimals, description, supply |
| Search tokens by name/symbol, with Aftermath Finance fallback |
| USD prices for tokens — current (Aftermath + Pyth), or historical via Pyth when |
Tool | Description |
| Reads up to 50 transactions in ONE call given their digests — sender, timing, balance changes, Move calls, and events with decoded fields. Ten digests go from ten round trips to one. Malformed digests are rejected before the request, because the server refuses a whole batch over one bad key |
| Transaction by digest with protocol-decoded actions |
| Filter transactions by sender, address, object, or function |
| Filter events by type, sender, module, or checkpoint range |
Tool | Description |
| DeFi positions across Suilend, Cetus, NAVI, Scallop, Bluefin, Bucket |
| Discover liquidity pools by token pair (Cetus, DeepBook, Turbos) |
| Pool reserves, fees, and prices for a given pool object ID (AMMs; see below for DeepBook) |
DeepBook v3 is a central limit order book, so it has no reserves. Depth, spread and traded price come from the DeepBook indexer rather than from a pool object. Mainnet and testnet only.
Tool | Description |
| Live bid/ask depth, spread, mid price and resting-liquidity imbalance. Omit |
| Recent fills with maker/taker balance manager IDs — attribute trading to an account during an incident window |
| (Security) Pyth oracle price vs the price DeepBook actually traded at, over a window — detects stale feeds, manipulation windows, and liquidations priced at levels the market never printed |
Tool | Description |
| List NFTs owned by a wallet, including kiosk-stored NFTs |
| Lightweight collection summary with counts |
| Holders of an NFT collection or token — a ranking only when the scan completes |
Tool | Description |
| List validators (stake, commission, voting power), or full detail for one when |
| Wallet's staking positions and pools |
Tool | Description |
| SuiNS name resolution (forward and reverse) |
The Move Registry maps human-readable package names like @suins/core or @deepbook/core to on-chain package addresses. Backed by mainnet.mvr.mystenlabs.com/v1 (or testnet.mvr... when SUI_NETWORK=testnet).
Tool | Description |
| Resolve one or many MVR names → package IDs. Accepts version-pinned names like |
| Reverse-lookup: package addresses → MVR names. Useful for enriching raw addresses anywhere. |
| Full record for a name: metadata, version, package_address, package_info ID, git source. |
| Browse / search the registry. Supports substring search, pagination, and an |
| Resolve |
Typical flows:
"What's the package for @deepbook/core?" → mvr_resolve(['@deepbook/core']) → 0x4874e1.... Hand the address to get_package for module/function details.
"What is package 0xf22f…?" → mvr_reverse_resolve(['0xf22f…']) → @suins/core.
"Find DeepBook-related packages" → mvr_search('deepbook', limit=20, is_linked=true) → paginated list.
"Pin to a specific version" → mvr_resolve(['@suins/core/3']) returns the v3 package address rather than the latest.
Tool | Description |
| Move package modules, structs (with ordered fields), and functions |
| Specific Move function signature and parameters |
| Package dependency analysis with recursive traversal |
| Summarize a package's API + heuristic risk scan (no binary; accepts 0x id or MVR name) |
| Disassemble Move bytecode via GraphQL (no binary; accepts 0x id or MVR name) |
| Decompile Move bytecode to source (requires decompiler binary) |
| (Security) Diff two package versions to spot what an upgrade changed — malicious-upgrade / backdoor detection |
Tool | Description |
| Build an unsigned transfer of SUI or any coin (auto coin selection); returns BCS for |
| Build an unsigned stake/unstake transaction ( |
| Dry-run a transaction to preview effects and gas cost |
Tool | Description |
| Decode a Programmable Transaction Block from BCS bytes |
| Monitor address or object for new activity since a checkpoint |
Tool | Description |
| Swap-aware, USD-valued multi-hop fund tracing that stops at labeled sinks (forward or backward) |
| Follow funds across a bridge, in either direction. Resolves Wormhole (VAA identity |
| Walk an address back to its funding source(s) for attribution; stops at labeled exchanges/bridges |
| Same, for up to 100 addresses in one call — shares work across converging chains, reports shared funders with flow shape, addresses paid by one transaction (weighed against that transaction's full recipient count), subjects that funded each other, and sub-minute funding bursts |
| Draw a random, reproducible control group from the same protocol and window, so a cohort's rate can be compared against chance |
| Find which of a protocol's package versions are actually emitting now — the bundled registry is a decode map full of historical IDs, and querying one returns nothing |
| How many distinct addresses a funder pays. Tells an exchange hot wallet apart from a real common origin |
| Finds addresses that may share an operator with the ones you give it, and shows the evidence. Multisig co-signature (read from the address hash, not inferred), shared first funder, direct funding, shared gas sponsor, or a third party paying both. Exchanges and relayers are measured and discarded first |
| For a multisig wallet, which committee keys are actually live and which have never signed, across its history. The committee is fixed for the life of the address; only who signs varies |
| Given addresses you suspect are related, derive every committee they could form and find the multisig they jointly control — a hit is proof, since the address IS the hash of its committee |
| Read a regulated coin's on-chain deny list — which addresses its issuer froze, or whether a given address is frozen for the coins it holds. Chain-derived: it is the issuer's own decision, reversible by whoever holds the DenyCap |
| Record a conclusion against a named case, so an investigation outlives its session |
| List findings in a case, or every case with its count |
| Render a case as a Markdown report, highest-confidence findings first |
| Retract a finding that turned out to be wrong |
| Rank wallets or event types by activity/value over a time window — "top wallets on this protocol today" in one call |
| Merge multiple addresses' activity into one checkpoint-ordered, protocol-decoded timeline |
| Object provenance: version history + ownership transitions (who created/held an object when) |
| Address-label registry (exchanges, bridges, mixers, malicious wallets) used by the tracing tools |
| Diff two package versions to detect malicious upgrades / backdoors |
(Recommended for token research) Get a comprehensive analysis of a Sui token in one call: metadata, current price, 24h change, total supply, and top 5 holders. Accepts either a coin type (e.g. '0x2::sui::SUI') or a name/symbol (e.g. 'DEEP', 'cetus').
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Token name, symbol (e.g. 'USDC', 'deep'), or full coin type (e.g. '0x2::sui::SUI') | |
| network | No | 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). | |
| include_holders | No | Include top 5 holders (default: true). Set false for faster response. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the returned data categories and input flexibility (coin type or symbol), but does not explicitly state that the call is read-only, nor does it mention rate limits, permissions, or error behavior. The 'get' and 'analysis' wording implies a safe read, but it is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence plus an example, front-loaded with the recommendation and specific output list. Every sentence provides useful information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description compensates by listing exactly what is returned (metadata, price, change, supply, holders) and the accepted input formats. It does not explain error handling or network-specific behavior, but those are partially covered in the schema, so the description is sufficiently complete for an analysis tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description's note about accepting coin type or symbol essentially restates the query parameter's own description. The description adds no extra semantics beyond what the schema already provides; hence, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Get a comprehensive analysis of a Sui token' and enumerates specific data points (metadata, current price, 24h change, total supply, top 5 holders), clearly distinguishing it from price-only tools like get_token_prices or balance tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Opens with '(Recommended for token research)' signaling the intended use case, and the description implies a comprehensive analysis without naming alternatives. However, it does not explicitly compare with sibling tools such as get_token_prices or identify_address, so it lacks explicit when-not instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn on additional Sui tool profiles for this session. This server ships a small default tool surface and keeps the rest one call away. Call this FIRST whenever the capability you need is not in your current tool list — the tool probably exists and is simply disabled. Do not reimplement a listed tool by hand.
'core' — Everyday lookups — wallets, balances, transactions, tokens, NFTs, DeFi positions. Tools: identify_address, get_wallet_overview, get_transaction, get_transactions, get_transaction_history, query_transactions, get_object, list_owned_objects, get_balance, analyze_token, get_token_prices, list_nfts, list_nft_collections, get_defi_positions, get_staking_summary, find_pools, resolve_name, get_chain_info 'forensics' — Incident investigation — fund tracing, batch funding attribution, address fan-out, live wallet-edge clustering, package analysis, multi-address timelines, object provenance, address labels, cross-chain bridge resolution, oracle-vs-market deviation, and recording findings into an exportable case report. Tools: resolve_protocol_packages, sample_control_addresses, trace_funds, resolve_bridge_transfer, find_funding_source, find_funding_sources, get_address_fanout, build_wallet_edges, analyze_multisig, find_shared_multisig, check_coin_restrictions, analyze_package, get_package, get_move_function, disassemble_module, build_timeline, trace_object_history, manage_labels, query_events, check_activity, get_top_holders, compare_oracle_price, aggregate_events, save_finding, list_findings, export_case, delete_finding 'developer' — Move package analysis — modules, disassembly, decompilation, upgrade diffing, dependency graphs, PTB decoding, unsigned transaction building, Move Registry. Tools: get_package, get_move_function, get_package_dependency_graph, analyze_package, disassemble_module, decompile_module, diff_package_upgrade, decode_ptb, simulate_transaction, build_transfer, build_staking, get_checkpoint, list_dynamic_fields, mvr_resolve, mvr_reverse_resolve, mvr_get_package_info, mvr_search, mvr_resolve_struct 'market' — Market data — DeepBook order book and fills, pool stats, token search, validators. Tools: deepbook_orderbook, deepbook_trades, get_pool_stats, search_token, get_coin_info, get_validators
Use 'all' for everything. Newly enabled tools are callable immediately.
| Name | Required | Description | Default |
|---|---|---|---|
| profile | No | Profile to enable, or 'all'. Accepts several: ['forensics','developer']. | |
| profiles | No | Alias for `profile`. Same values; use whichever reads better. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explains the session-scoped effect ("for this session"), the lazy-enablement model, and the consequence ("Newly enabled tools are callable immediately"). It does not describe the return value or what happens if a profile is already enabled, but the core behavioral traits are clearly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured: purpose, usage rule, then a consistent profile-by-profile layout ending with the 'all' shortcut and immediate availability. The forensics profile's prose is somewhat dense and lists many capabilities in a run-on style, but the overall structure is navigable and front-loaded with the most important guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's meta-purpose and minimal schema, the description is complete: it explains when to call it, what each parameter value grants, which tools become available, and that effects are immediate. No output schema exists, but the outcome of calling this tool is the availability of other tools, which is fully stated. There are no missing details an agent would need to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the schema only says "Profile to enable, or 'all'." The description adds substantial semantic value by enumerating each profile ('core', 'forensics', 'developer', 'market'), describing its domain, listing the exact tools it enables, and clarifying the special value 'all'. It also explains the alias relationship by saying the `profiles` parameter takes the same values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Turn on additional Sui tool profiles for this session." It also clarifies what the tool is not by explaining that the server "ships a small default tool surface and keeps the rest one call away," which distinguishes it from the individual lookup tools listed as siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage guidance is explicit: "Call this FIRST whenever the capability you need is not in your current tool list — the tool probably exists and is simply disabled." It also warns against an incorrect alternative behavior: "Do not reimplement a listed tool by hand." This is direct, actionable, and leaves no ambiguity about when to invoke the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find DeFi liquidity pools by token pair. Searches Cetus, DeepBook, and Turbos for pools matching the given tokens. Use get_pool_stats on a returned pool_id for detailed stats.
| Name | Required | Description | Default |
|---|---|---|---|
| network | No | 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). | |
| token_a | Yes | First token: symbol (e.g. 'SUI') or full coin type | |
| token_b | Yes | Second token: symbol (e.g. 'USDC') or full coin type | |
| protocol | No | Filter by protocol: 'cetus', 'deepbook', or 'turbos'. Searches all if omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full transparency burden. It reveals that the tool searches across specific DEXs and returns a pool_id, but does not disclose result format, potential empty results, sorting, or pagination behavior. This is adequate for a simple read-only search but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences: the first states purpose, the second explains search scope, the third points to a follow-up. No filler or redundancy; purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no output schema, the description covers the primary use case, the exact protocols searched, and a clear next step. It mentions pool_id as a return field, but does not describe the full result structure or edge case behavior. Still, it is sufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions for token_a, token_b, network, and protocol. The tool description only mentions 'token pair' and 'tokens', which adds no meaning beyond the schema. The baseline of 3 applies because the schema carries the semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Find DeFi liquidity pools by token pair' — a specific verb and resource that clearly states the tool's function. It also names three protocols (Cetus, DeepBook, Turbos) it searches, which differentiates it from adjacent tools like get_defi_positions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: use when you have a token pair and need to find matching liquidity pools. It explicitly recommends get_pool_stats for subsequent detail, giving a follow-up path. However, it does not contrast with siblings or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the liquid balance of one coin type for a Sui address (defaults to SUI), optionally at a historical checkpoint. This counts spendable coins ONLY: 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.
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Owner address (0x...) | |
| network | No | 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). | |
| coin_type | No | Coin type (default: 0x2::sui::SUI) | |
| at_checkpoint | No | Query balance at a specific checkpoint (for historical balances) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It clearly discloses that only spendable/liquid coins are counted and explicitly calls out exclusions (staked SUI, DeFi positions), which is exactly the kind of non-obvious behavior an agent needs. It does not describe return format or unit handling, but the core behavioral ambiguity is well addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the primary action, and every sentence adds distinct value: the core function, the critical exclusions/nuance, and the sibling alternative. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers selection, semantics, and the main edge cases, which is strong for a 4-parameter tool. However, there is no output schema and the description does not specify the return unit or format of the balance value. This is a minor gap but still leaves some ambiguity for an agent invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already documents owner, network, coin_type, and at_checkpoint, including defaults. The description adds the important 'liquid only' framing and the distinction from other tools, but it does not significantly expand on the individual parameters beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get the liquid balance of one coin type for a Sui address'. It also notes the SUI default and the optional historical checkpoint, and clearly distinguishes itself from get_wallet_overview (all coins at once) and get_staking_summary/get_defi_positions (non-liquid holdings).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use and when-not-to-use guidance. It states that staked SUI and DeFi value are excluded, advises pairing with get_staking_summary and get_defi_positions before drawing conclusions, and directs users to get_wallet_overview when every coin type is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current Sui network info: chain ID, epoch, checkpoint height, timestamp, and reference gas price. Optionally pass an epoch number to get details for a specific epoch.
| Name | Required | Description | Default |
|---|---|---|---|
| epoch | No | Epoch number to query. Returns current epoch info if omitted. | |
| network | No | 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). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It lists the returned fields, which gives insight into output, and implies a read-only operation. However, it does not explicitly state side effects, error behavior, or default network selection, leaving some gaps for a complete transparency profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and every word adds value. It avoids repetition and clearly introduces the optional parameter in the second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, no annotations, and fully described schema, the description covers the essential behavior. It names all returned fields and explains the epoch option. The lack of an output schema is partially compensated by the field list, though a more explicit response structure could improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes both parameters with high coverage (100%). The description's mention of 'optionally pass an epoch number' reinforces but does not add new semantic detail beyond the schema. The network parameter's detailed description is already in the schema, so the description adds no extra value here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get current Sui network info' and enumerates specific fields (chain ID, epoch, checkpoint height, timestamp, reference gas price), making the tool's function unambiguous. It is distinct from sibling tools like get_object or get_transaction, which target other data types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear use case: retrieving current network info, and also explains the optional epoch parameter for querying specific epochs. While it does not explicitly name alternatives or exclusion criteria, the context is sufficient given that no sibling tool offers this functionality.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find DeFi positions owned by a Sui wallet across major protocols: Suilend, Cetus LP, NAVI, Scallop, Bluefin, Bucket, and staked SUI. Returns extracted position summaries (deposits, borrows, liquidity, fees) instead of raw on-chain data.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | Wallet address (0x...) | |
| network | No | 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). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the transparency burden. It discloses a key behavioral trait: it returns extracted position summaries (deposits, borrows, liquidity, fees) rather than raw on-chain data. However, it offers no detail on permissions, pagination, or behavior for addresses with no positions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact at two sentences, starts with the action, and includes an enumerated list of protocols without extraneous language. Every sentence contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description outlines the tool's scope and the nature of the returned data, which is important because no output schema is provided. It could be more explicit about return edge cases (e.g., empty positions) or network-specific behavior, but the schema's full coverage of network/address parameters helps. Overall, it is sufficient for an agent to decide when to invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents both parameters (address and network) with descriptions, so the baseline is 3. The tool description doesn't add any additional parameter-level semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: finding DeFi positions owned by a Sui wallet. It enumerates covered protocols (Suilend, Cetus LP, NAVI, Scallop, Bluefin, Bucket, and staked SUI), which differentiates it from sibling tools like get_balance or get_staking_summary. The verb 'Find' and resource 'DeFi positions' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a wallet's DeFi positions across specific protocols are needed, but it provides no explicit guidance on when to choose this tool over siblings such as get_wallet_overview or get_staking_summary. There are no stated exclusions or alternative tool recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a Sui object by its ID. Returns type, owner, version, content (JSON), and digest. Automatically extracts display metadata (name, description, image_url) for NFTs.
| Name | Required | Description | Default |
|---|---|---|---|
| network | No | 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). | |
| version | No | Specific version to fetch | |
| object_id | Yes | The object ID (0x...) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by listing the returned fields (type, owner, version, content JSON, digest) and the automatic extraction of NFT display metadata. It could be more thorough about error handling, but it clearly conveys the operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, starts with the main action, and has no filler or redundant content. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool, the description adequately explains the output and special NFT handling. The parameter schema is comprehensive, and no output schema exists. It lacks sibling comparison guidance, but that is covered under usage guidelines. Overall, it is complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already contains full descriptions for all three parameters (object_id, network, version), so the description adds no additional parameter detail. Per the rubric, a baseline of 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a Sui object by its ID', which specifies the exact action and target. It distinguishes itself from sibling tools like list_owned_objects and get_transaction by focusing on retrieving a single object by ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied: use this when you have a specific object ID to fetch. However, it does not explicitly state when to prefer this over alternatives like list_owned_objects, nor does it mention any exclusions or complementary tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a wallet's staking positions: every StakedSui object with its validator pool, principal, and activation epoch. Worth calling during an investigation or a net-worth check, because staked SUI does NOT appear in get_balance — a wallet that looks nearly empty can hold a large staked position, and the stake also ties it to a specific validator.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | Wallet address (0x...) | |
| network | No | 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). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden and does so well: it reveals that staked SUI is omitted from get_balance, that the tool surfaces these otherwise-hidden positions, and that the result ties the wallet to a specific validator. It could add details about errors or pagination, but the key non-obvious behavior is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two focused sentences: the first states the tool's core behavior, the second provides the critical usage context. There is no filler or repetition, and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with only one required parameter and a fully documented schema, the description is complete: it explains what is returned, why the tool matters, and how it relates to get_balance. No output schema exists, so the return-value details in the description are especially valuable and sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well documented. The description adds no additional parameter-level detail beyond what the schema provides, keeping this at the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific operation ('Get a wallet's staking positions'), a concrete resource ('every StakedSui object'), and the exact data returned (validator pool, principal, activation epoch). It also differentiates from get_balance by explicitly noting that staked SUI does not appear in balance results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool ('during an investigation or a net-worth check') and explains the gap with get_balance. It does not explicitly state when not to use it or mention overlapping alternatives such as get_defi_positions, so it lacks a full exclusion list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get USD prices for Sui tokens — current by default, or historical when at is set. Current prices use Aftermath (primary) + Pyth (fallback); historical prices use the Pyth oracle at the given time. Accepts full coin type strings (e.g. 0x2::sui::SUI).
| Name | Required | Description | Default |
|---|---|---|---|
| at | No | Optional: price AT this point in time — Unix seconds or ISO 8601 (e.g. '2025-01-15T00:00:00Z'). Omit for current prices. | |
| network | No | 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). | |
| coin_types | Yes | Array of full coin type strings (e.g. ['0x2::sui::SUI', '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC']) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral disclosure burden. It reveals that current prices use Aftermath with Pyth as fallback, and historical prices rely on the Pyth oracle at the given time, which provides meaningful insight into data source reliability. However, it does not mention failure modes (e.g., what happens if a price is unavailable) or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using three short sentences to convey the primary purpose, data source behavior, and input format. Every sentence adds value with no fluff, and the most important information (what it does) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only price query tool with no output schema, the description covers the core functionality, historical vs. current behavior, data sources, and required input format. It lacks explicit return structure (e.g., mapping from coin type to price) but the simplicity of the tool makes this acceptable. The network parameter is not mentioned in the description, though it is thoroughly documented in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters are fully described in the schema (100% coverage), so the description adds only redundant reinforcement (e.g., 'Accepts full coin type strings'). It does not provide new semantic meaning beyond the schema, such as return format or unit details, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets USD prices for Sui tokens, with a specific distinction between current and historical prices via the `at` parameter. It also specifies the data sources (Aftermath, Pyth) and input format, making it distinct from sibling tools like get_balance or analyze_token.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use current vs. historical modes (when `at` is set) but does not explicitly compare against alternative sibling tools like analyze_token. It provides context on data source fallback but lacks explicit 'use this when' or 'instead of' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a Sui transaction by its digest. Returns sender, status, gas, balance changes, protocol-aware decoded actions (e.g. 'swap on Cetus', 'deposit on Suilend'), and events WITH their decoded fields — so there is no need to hand-write GraphQL to read an event's values. Protocols are identified from the events as well as the Move calls, which matters when a transaction calls an obfuscated wrapper: protocols_from_events_only marks that case.
| Name | Required | Description | Default |
|---|---|---|---|
| digest | Yes | Transaction digest (Base58) | |
| network | No | 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). | |
| max_event_field_bytes | No | Optional byte cap on decoded event fields. UNSET BY DEFAULT: every event comes back with its fields, because an investigation must not be silently working from a subset. Set this only when you knowingly want to bound the payload — anything skipped is reported — or set 0 to skip decoding entirely. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It is transparent about returned fields, decoded event values, and the protocol-identification nuance for obfuscated wrappers, plus the default behavior for max_event_field_bytes is covered in the schema. It does not describe not-found handling or errors, but the disclosed behavior is material and specific enough for an agent to understand what happens when the tool is called.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded and the description is information-dense, explaining why decoded events matter and flagging the obfuscated-wrapper edge case. It is slightly long, but every clause adds value and there is no filler; the examples such as 'swap on Cetus' make the behavior concrete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description does a strong job of covering return contents and a subtle behavioral edge case, which is enough for a read-style tool. It could also specify behavior for missing digests or error responses and clarify where the `protocols_from_events_only` marker appears, but nothing essential for invoking with a digest is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents digest, network, and max_event_field_bytes. The description adds little parameter-specific meaning beyond contextualizing decoded event fields; it mostly reinforces schema guidance. Baseline 3 is appropriate since the structured schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource: 'Get a Sui transaction by its digest.' It goes beyond a generic getter by enumerating the exact payload — sender, status, gas, balance changes, decoded events and protocol-aware actions — and 'by its digest' clearly separates it from sibling listing/query tools like query_transactions and get_transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for fetching a single transaction when the caller already has a digest, and it communicates the value of getting decoded event fields without hand-writing GraphQL. However, it never explicitly states when to prefer this over query_transactions/get_transactions, nor does it give exclusions, so the usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
(Recommended for wallet activity) Get decoded transaction history for a Sui wallet. Returns a human-readable activity feed with protocol names (e.g. Cetus, Suilend), action descriptions (e.g. 'Swap USDC → SUI'), and token flow. Prefer this over query_transactions when exploring what a wallet has been doing.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Pagination cursor for next page | |
| limit | No | Number of transactions to return (default 10, max 50) | |
| address | Yes | Sui wallet address (0x...) | |
| network | No | 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). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It adds valuable context by describing the output as 'decoded' and 'human-readable,' implying a read-only, user-friendly feed. But it does not mention any potential limitations, rate limits, or error behavior, leaving some transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each serving a clear purpose: stating recommendation, defining functionality with concrete examples, and providing usage guidance. There is no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the full schema coverage for parameters and a clear, detailed description of purpose and output, the description is nearly complete. It could mention pagination or network behaviors explicitly, but those are already covered by the schema, so it does not need to.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning all parameters are already documented in the input schema. The description adds no additional parameter-specific guidance beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: to get decoded transaction history for a Sui wallet, with specific output details like protocol names and token flow. It also distinguishes itself from the sibling query_transactions by explicitly recommending it for exploring wallet activity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context with 'Recommended for wallet activity' and directly names an alternative: 'Prefer this over query_transactions when exploring what a wallet has been doing.' However, it lacks a clear 'when not to use' statement, so it doesn't fully cover both sides.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read up to 50 Sui transactions in ONE call, given their digests. Returns sender, status, timing, balance changes, Move call targets and events WITH their decoded fields for each, plus the protocols involved. Use this whenever you hold several digests at once — the outputs of a fan-out, the evidence on a cluster edge, a set of hops to compare — instead of calling get_transaction repeatedly; ten digests go from ten round trips to one. Digests that could not be read come back in not_found rather than being dropped. For ONE transaction, or for a transaction with more than 50 events, prefer get_transaction: it pages events to the end.
| Name | Required | Description | Default |
|---|---|---|---|
| digests | Yes | Transaction digests, Base58 (1-50). Duplicates are collapsed. | |
| network | No | 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). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. It reveals that not-found digests are returned in a `not_found` list rather than dropped, that duplicates are collapsed (in schema as well), and that get_transaction should be used when there are more than 50 events because this batch tool pages events differently. It also clearly frames the operation as read-only by starting with 'Read', which is important since no readOnlyHint is available.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every clause earns its place. It front-loads the core capability, then return contents, then concrete use cases, then edge-case behavior, then the alternative. It avoids filler and is organized so an agent can quickly extract purpose, usage, and limitations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, no-output-schema tool, this description is remarkably complete. It specifies input semantics (digests, network), batch limit (50), behavior when digests are missing, return value highlights, and the boundary with the single-transaction sibling. An agent has enough information to select the tool and invoke it correctly for both common and edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both `digests` and `network` already include detailed descriptions in the schema, including Base58 format, min/max items, duplicate collapsing, and network enum semantics. The tool description does not add meaning beyond what the schema provides for these parameters; it only adds usage context. This meets the baseline for high schema coverage but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-object pair: 'Read up to 50 Sui transactions in ONE call, given their digests.' It clearly identifies the resource (transactions by digest), the batch scope, and the key returned fields (sender, status, timing, balance changes, move call targets, events with decoded fields, protocols). It also explicitly contrasts with the sibling get_transaction, making differentiation effortless.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'Use this whenever you hold several digests at once' with concrete examples (fan-out outputs, cluster edge evidence, hops to compare). It states the alternative and the exact condition for switching: 'For ONE transaction, or for a transaction with more than 50 events, prefer get_transaction.' No inference is required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
(Recommended first tool for wallets) Get a comprehensive overview of a Sui wallet: all token balances, SuiNS name, staked SUI count, kiosk/NFT count, and recent transactions. Set include_prices=true for USD values and total portfolio value. Start here before drilling into specific tools.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | Wallet address (0x...) | |
| network | No | 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). | |
| include_prices | No | Include USD prices and portfolio value (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the scope of the return data (balances, SuiNS, staking, NFTs, transactions) and the include_prices option for USD values. However, it omits potential caveats such as pagination, performance limits, or network-specific behavior, which leaves some gaps for a comprehensive aggregate tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, with the first sentence front-loading the tool's purpose and contents, and the second giving a concise parameter tip. Every word earns its place, and there is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although there is no output schema, the description sufficiently enumerates the major return categories (token balances, SuiNS name, staked SUI count, kiosk/NFT count, recent transactions) and explains the optional price inclusion. It also provides a clear usage context relative to sibling tools. It does not detail the exact result structure, but for a high-level overview tool this is acceptable and the sibling tools can provide more depth.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all parameters with detailed descriptions (100% coverage), so the baseline is 3. The description adds marginal value by highlighting include_prices as the way to get USD values and portfolio value, but this largely mirrors what the schema already explains. No additional syntax or format details are provided beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a clear verb ('Get') and resource ('comprehensive overview of a Sui wallet'), and explicitly enumerates the included data (token balances, SuiNS name, staked SUI count, kiosk/NFT count, recent transactions). It also positions itself as the recommended first tool, which distinguishes it from sibling tools like get_balance or list_nfts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Recommended first tool for wallets' and 'Start here before drilling into specific tools.' It clearly indicates when to use this tool as an entry point and implies that more specific tools should be used afterward. It does not name specific alternative tools, but the directive is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
(Recommended first step) Identify what a Sui address is: wallet, package, validator, or object. Returns a type classification with contextual summary (e.g. balance + SuiNS for wallets, module list for packages, stake info for validators). Use this before deciding which other tools to call.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | Sui address or object ID (0x...) | |
| network | No | 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). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It clearly states that the tool returns a type classification plus contextual summaries with specific examples (balance + SuiNS for wallets, module list for packages, stake info for validators). This conveys the operational behavior and output richness without needing to describe side effects (as it is a read-only identification).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences. The first sentence states the core purpose and classification types; the second sentence describes the output and provides usage guidance. Every sentence earns its place, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema, no annotations), the description covers the essential function, the nature of the return value, and when to use it relative to other tools. It is complete enough for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds general context about what the return will be but does not add parameter-level detail beyond the schema. The schema already clearly describes 'address' and 'network', so the description is not required to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Identify') and resource ('Sui address'), and clearly enumerates the classification categories (wallet, package, validator, object). This distinguishes it from sibling tools that query specific types (e.g., get_object, get_balance).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends it as the 'Recommended first step' and says 'Use this before deciding which other tools to call,' giving clear when-to-use context. It does not explicitly name alternatives or state when not to use it, but the positioning is sufficient for a helper/classifier tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a lightweight summary of NFT collections owned by a wallet. Walks all kiosks plus direct-owned objects and returns deduplicated collection types with counts. Backed by GraphQL.
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | Owner wallet address (0x...) | |
| network | No | 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). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It discloses key behaviors: it walks multiple sources ('kiosks plus direct-owned objects'), deduplicates, and returns a 'lightweight summary' with counts. It also mentions 'Backed by GraphQL' as an implementation detail. This adds meaningful context beyond the tool name and schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose in the first sentence and behavioral details in the second. Every sentence adds value without redundancy or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a read-only summary tool. It explains what the tool does, how it operates (walking kiosks and direct-owned objects), what the output contains (deduplicated collection types with counts), and is backed by GraphQL. Given the simple two-parameter schema and absence of an output schema, the description sufficiently covers the tool's behavior and expected result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for both parameters (address and network). The description does not add additional parameter-specific meaning beyond what the schema already states. Per the baseline rule for high schema coverage, this is a 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get a lightweight summary of NFT collections owned by a wallet.' It specifies the resource and action, and further clarifies scope by mentioning 'Walks all kiosks plus direct-owned objects and returns deduplicated collection types with counts,' distinguishing it from siblings like list_nfts and list_owned_objects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear use case: obtaining a high-level NFT overview. It provides context by explaining it traverses kiosks and direct-owned objects and returns deduplicated collection types, which helps differentiate it from more detailed tools. However, it does not explicitly name alternatives or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
(Recommended for NFTs) List NFTs owned by a wallet, including kiosk-stored NFTs. Returns display metadata (name, description, image URL) and raw Move struct contents inline. Backed by GraphQL — single query per kiosk page, no fullnode rate-limit risk. Pagination: pass cursor from a prior response to fetch the next page; the response omits next_cursor when the wallet is fully enumerated. May slightly overshoot limit because GraphQL pages are 50-at-a-time and we don't break mid-page. Use list_nft_collections for a cheaper count-only summary.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Target page size (default 50, max 1000). Result may slightly exceed this at GraphQL page boundaries. | |
| cursor | No | Opaque pagination token from a prior response's `next_cursor`. Omit on first call. | |
| address | Yes | Owner wallet address (0x...) | |
| network | No | 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). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full responsibility. It discloses pagination behavior ('pass cursor... next_cursor omitted when wallet is fully enumerated'), GraphQL page-boundary overshoot, and response contents (display metadata + raw Move structs). This is exceptionally transparent for a list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: scope, response contents, backend rationale, pagination mechanics, and alternative. No filler or redundancy; front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations or output schema, the description fully covers what the tool does, when to use it, how pagination works, and which sibling covers a different need. It leaves no ambiguity for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 4 params with descriptions (100% coverage), so baseline is 3. Description adds meaning to limit and cursor by explaining the overshoot rationale and the next_cursor omission behavior, which goes beyond schema text. Incremental context justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List NFTs owned by a wallet, including kiosk-stored NFTs' — a specific verb, resource, and scope. It also explicitly says '(Recommended for NFTs)' which differentiates it from sibling tools like list_owned_objects and list_nft_collections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit alternative: 'Use list_nft_collections for a cheaper count-only summary.' Also explains the GraphQL backend benefit ('no fullnode rate-limit risk') which clarifies when this tool is preferable to fullnode-backed alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List raw objects owned by a Sui address with optional type filter and pagination. For NFTs specifically, prefer list_nfts (resolves kiosk storage, extracts display metadata). For a wallet summary, prefer get_wallet_overview.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 50, max 1000) | |
| owner | Yes | Owner address (0x...) | |
| cursor | No | Pagination cursor from previous response | |
| network | No | 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). | |
| object_type | No | Filter by object type (e.g. 0x2::coin::Coin<0x2::sui::SUI>) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses key behavioral traits such as 'raw' (no kiosk resolution, no display metadata) and pagination support. However, it does not explain the return format or any potential limitations, leaving some ambiguity for a tool that lists raw objects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise, front-loaded sentences. The first sentence states the core function; the second gives alternative guidance. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so return values are not documented. While the description clearly covers primary purpose and when to use alternatives, it leaves the exact structure of a 'raw object' response unspecified. Given the schema covers all parameters and the alternatives are well-stated, the description is mostly complete but not fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 5 parameters. The description merely mentions 'optional type filter and pagination', adding no new meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States clearly it lists raw Sui objects owned by an address, with optional type filter and pagination. It distinguishes itself from sibling tools by explicitly contrasting with list_nfts and get_wallet_overview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance by directing NFT queries to list_nfts and wallet summaries to get_wallet_overview. This clearly maps scenarios to the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query raw Sui transactions with specific filters (sender, affected address/object, function, checkpoint range). Note: only ONE of affected_address, affected_object, or function can be used per query (Sui GraphQL limitation). For human-readable wallet activity, prefer get_transaction_history instead.
ATTRIBUTION WARNING: the function filter matches any transaction containing that call, including PTBs where it is one leg among several protocols. A transaction's balance changes cover the WHOLE PTB, so summing them per protocol over-attributes — a big Cetus swap in the same PTB will be counted as your protocol's volume. Set include_functions to see every Move call in each transaction, and prefer the protocol's own events (query_events) when measuring per-protocol flow.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Pagination cursor | |
| limit | No | Max results (default 20) | |
| sender | No | Filter by sender address | |
| network | No | 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). | |
| function | No | Filter by Move function (e.g. 0x2::coin::transfer or 0x2::pay). Mutually exclusive with affected_address and affected_object. | |
| affected_object | No | Filter by affected object ID. Mutually exclusive with affected_address and function. | |
| affected_address | No | Filter by affected address (sender, sponsor, or recipient). Mutually exclusive with affected_object and function. | |
| after_checkpoint | No | Only transactions after this checkpoint | |
| before_checkpoint | No | Only transactions before this checkpoint | |
| include_functions | No | Return every Move call in each transaction, so you can see whether the filtered package was the whole transaction or one leg of a multi-protocol PTB. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It reveals the Sui GraphQL limitation (only one of affected_address, affected_object, or function may be used), explains the PTB attribution pitfall, and describes how include_functions mitigates it. This is high-value behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but structured into a purpose/guidance section and a warning paragraph. Each sentence earns its place, though the attribution warning is dense. It is appropriately detailed for a complex tool with 10 parameters but not perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter tool with no output schema and no annotations, the description covers the most important contextual concerns: filter exclusivity, PTB attribution, and alternative tools. It stops short of describing the return shape or pagination behavior, but the raw transaction intent is clear enough for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description enhances the meaning of tricky parameters: it explains why function filtering is dangerous for attribution and when to use include_functions. However, most parameter details are left to the schema, so the gain is modest but non-trivial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Query raw Sui transactions with specific filters' and enumerates the filter types (sender, affected address/object, function, checkpoint range), making the tool's scope immediately clear. It also distinguishes itself from the sibling tool get_transaction_history by labeling itself 'raw' and explicitly directing human-readable queries to that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'For human-readable wallet activity, prefer get_transaction_history instead' and warns against using the function filter for per-protocol volume metrics, suggesting query_events as the alternative. It also states the mutual-exclusivity constraint among three filters, which is a crucial usage rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a SuiNS name (.sui domain) to an address, or reverse-lookup an address to its SuiNS name. At least one of 'name' or 'address' must be provided.
IDENTITY WARNING: a SuiNS name is a self-chosen handle that anyone can buy. It is not identity and it is not verified. Names matching an exchange, a project or a person can be — and are — registered by unrelated parties, including by someone who wants an investigator to draw a particular conclusion. Treat a name as a label the holder picked, never as evidence of who they are, and do not carry it to other platforms as a matching key without independent corroboration.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | SuiNS name to resolve (e.g. 'example.sui') | |
| address | No | Address to reverse-lookup to a SuiNS name | |
| network | No | 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). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden, and it does well by adding a substantial identity warning: SuiNS names are self-chosen, unverified, and potentially misleading. It does not detail response format, error behavior, or explicit read-only status, but for a lookup tool the main behavioral risks are addressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The functional description is front-loaded and unambiguous, and the identity warning is long but substantive in an investigative context. No sentences are wasted, though the warning could be slightly tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The key constraint is stated and the lookup behavior is clear, but with no output schema the agent is left without return-shape or failure-mode information. It also does not specify what happens when both name and address are supplied, which is a plausible edge case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all three parameters, so the baseline is 3, but the description adds the critical at-least-one requirement and clarifies that name and address are opposite directions of the same lookup. It also gives a concrete .sui example and the identity warning adds meaning to the name parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states the exact operation: resolving a SuiNS name to an address and reverse-looking-up an address to a name. It is specific, anchored to the .sui namespace, and clearly distinct from sibling tools like identify_address or get_object.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explain when to prefer this tool over alternatives, nor does it name any sibling tool or exclusion condition. The 'at least one of name or address' sentence is an invocation constraint rather than usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.12.1enable_tools4 fields changedInput schema / properties / profile / anyOfPrevious value: -[
- {
- "enum": [
- "core",
- "forensics",
- "developer",
- "market"
- ],
- "type": "string"
- },
- {
- "const": "all",
- "type": "string"
- }
-]New value: +[
+ {
+ "anyOf": [
+ {
+ "enum": [
+ "core",
+ "forensics",
+ "developer",
+ "market"
+ ],
+ "type": "string"
+ },
+ {
+ "const": "all",
+ "type": "string"
+ }
+ ]
+ },
+ {
+ "items": {
+ "$ref": "#/properties/profile/anyOf/0"
+ },
+ "type": "array"
+ }
+]Input schema / properties / profile / descriptionPrevious value: -"Profile to enable, or 'all'."New value: +"Profile to enable, or 'all'. Accepts several: ['forensics','developer']."Input schema / properties / profilesAdded value: +{
+ "$ref": "#/properties/profile",
+ "description": "Alias for `profile`. Same values; use whichever reads better."
+}Input schema / requiredRemoved value: -[
- "profile"
-]get_transaction1 field changedInput schema / properties / max_event_field_bytesAdded value: +{
+ "description": "Optional byte cap on decoded event fields. UNSET BY DEFAULT: every event comes back with its fields, because an investigation must not be silently working from a subset. Set this only when you knowingly want to bound the payload — anything skipped is reported — or set 0 to skip decoding entirely.",
+ "maximum": 500000,
+ "minimum": 0,
+ "type": "integer"
+}get_transactionsv1.5.0analyze_tokenenable_toolsfind_poolsget_balanceget_chain_infoget_defi_positionsget_objectget_staking_summaryget_token_pricesget_transactionget_transaction_historyget_wallet_overviewidentify_addresslist_nft_collectionslist_nftslist_owned_objectsquery_transactionsresolve_nameScored across 19 tools
The tool surface has overlapping tools for similar purposes: get_transaction vs get_transactions vs query_transactions vs get_transaction_history; get_object vs list_owned_objects vs list_nfts; find_pools vs get_pool_stats vs search_token. However, descriptions provide enough hints (e.g., raw vs decoded, count-only) to reduce confusion, though an agent may still pick the wrong one.
Most tools follow a consistent verb_noun pattern (get_, list_, resolve_, find_, analyze_, build_, etc.) with clear object names. A few deviations like 'mvr_resolve' and 'disassemble_module' (no 'get') and the profile names 'enable_tools' are acceptable, but overall the pattern is predictable.
With 19 tools listed, the surface is already sizeable, but the server expects dynamic loading of additional tools (e.g., 'all' profile) which could push the true count to over 100. This feels overwhelming and excessive for a single server. The default 19 is borderline, but the full capability scope is too broad.
The tool set covers a comprehensive range of Sui operations: address identification, wallet overview, balances, transactions (raw and decoded), NFTs, DeFi, staking, token analysis, price data, pool discovery, name resolution, chain info, and historical queries. The coverage is thorough, and the descriptions include cross-tool guidance (e.g., get_balance vs staking) that prevents dead ends. The forensics and developer profiles add more depth, making the surface effectively complete for the domain.
Free read-only crypto whale-tracking & market-data MCP tools across 14 chains. No auth.
Solana on-chain intelligence — token scans, wallet profiling, bundle detection, 19 MCP tools.
Solana MCP for wallets, trades, markets, PnL, transfers, onchain data, signable swaps and API tools.
Self-hosted MCP server: 26 deterministic dev, security, and EVM tools.
