Skip to main content
Glama

ERC-20 balance of an address for one token contract

evm_balance
Read-only

ERC-20 balance of an address for one token contract on a chain: token name, symbol, decimals, raw and human amount, and a USD value when Coinbase has a spot price for the symbol. Only the token you name is read; the native balance is in /api/evm/address. Related tools on this server, for a different need: evm_address when you need native balance, nonce and account type of an EVM address; evm_nft when you need ERC-721 facts for one token: owner, collection name. Price: $0.002 per successful call, paid with x402 (USDC on Base, Solana and 10 more networks); failed calls are not charged.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "address": "<address>",
      "token": "<token>"
    },
    "name": "evm_balance"
  }
}

Input Schema

NameRequiredDescriptionDefault
chainNobase (default), ethereum, arbitrum, optimism or polygon
tokenYesERC-20 contract address, 0x…
addressYesEVM address, 0x…

Output Schema

NameRequiredDescriptionDefault
rawNo
chainNo
tokenNo
amountNo
holderNo
sourceNo
usdPriceNo
usdValueNo
checkedAtNo
disclaimerNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare readOnly and openWorld; the description adds the payment model the annotations cannot convey — $0.002 per successful call via x402 (USDC on Base, Solana and 10+ networks), with failed calls not charged. It also discloses the conditional nature of the USD field ('when Coinbase has a spot price'), which tells the agent the price field may be absent.

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

Conciseness4/5

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

Core purpose and scope constraints are front-loaded in the first sentence, with routing and pricing after. Slightly padded by the framing phrase 'Related tools on this server, for a different need' before an already self-explanatory list, but nothing is wasted or buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-parameter read tool with a full output schema and readOnly annotations, the definition covers everything an agent needs: what it reads, what it excludes, when to choose a sibling, and the cost/authorization model. No dependency is left for the caller to guess.

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

Parameters3/5

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

Schema coverage is 100%, and the schema already documents chain options, including 'base (default)', plus token and address. The description adds only the scoping rule that just the named token is read; it gives no extra format or constraint detail for the parameters themselves. Baseline 3 applies where the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+scope: 'ERC-20 balance of an address for one token contract on a chain', and enumerates what is returned (name, symbol, decimals, raw/human amount, USD value). It explicitly distinguishes itself from evm_address (native balance) and evm_nft (ERC-721), so an agent can route without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States the selection condition for siblings explicitly: 'evm_address when you need native balance, nonce and account type' and 'evm_nft when you need ERC-721 facts'. It also bounds scope positively ('Only the token you name is read') and points to /api/evm/address for the other case, leaving no ambiguity about when to call this tool.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources