Femtos

Token holders

get_holders

Read-onlyIdempotent

Largest holders of a token and its concentration (top-10 share…); system addresses (pools, bridges, launchpad, zero/dead) counted apart. hypercore: token = name (HYPE), kind = balances (spot) or positions (perp open interest of a coin); hyperevm / elysium: token = 0x address. Named wallets carry entity; EVM rows say what each address is (label, labelKind: pool, bridge, protocol, token, creator, multisig, contract, wallet; contract: has code) and what each holder did with the token: pnl (buys / sells since its first swap, average entry price and market cap, realized / unrealized PnL) and tags (dev, sniper, bundler, insider, pro); tagShares = supply held by snipers, bundlers, insiders, pro traders, the creator among the 100 largest (proHolders: how many pro traders).

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": {
      "token": "<token>"
    },
    "name": "get_holders"
  }
}

Input Schema

Name	Required	Description
`kind`	No	HyperCore: spot balances of a token, or perp positions (open interest by account) of a coin (spot / perp: the same). Default: positions for a perp coin, else balances
`layer`	No	Layer (default hypercore)
`limit`	No	Rows (default 50)
`token`	Yes	Token address (Elysium, HyperEVM), token name or perp coin (HyperCore)
`network`	No	Elysium network: mainnet or testnet, same answers (testnet USD values null). HyperCore and HyperEVM are always mainnet (default mainnet)
`excludeSystem`	No	1 / true: pools, PoolManager, hooks, gateways, bridge system addresses, LiquidLaunch curve, zero/dead counted apart; 0 / false: counted with the others (default true)

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 30, 2026

addedInput schema / properties / network

Added value: +{
+  "description": "Elysium network: mainnet or testnet, same answers (testnet USD values null). HyperCore and HyperEVM are always mainnet (default mainnet)",
+  "enum": [
+    "mainnet",
+    "testnet"
+  ],
+  "type": "string"
+}

Changed1 schema field changedOct 22, 2026
- addedInput schema / required
```
Added value: +[
+  "token"
+]
```

Changed11 schema fields changedOct 22, 2026

addedInput schema / properties / excludeSystem

Added value: +{
+  "description": "1 / true: pools, PoolManager, hooks, gateways, bridge system addresses, LiquidLaunch curve, zero/dead counted apart; 0 / false: counted with the others (default true)",
+  "type": "boolean"
+}

changedInput schema / properties / kind / description

Previous value: -"hypercore: spot balances (default) or perp positions"New value: +"HyperCore: spot balances of a token, or perp positions (open interest by account) of a coin (spot / perp: the same). Default: positions for a perp coin, else balances"

changedInput schema / properties / kind / enum

Previous value: -[
-  "balances",
-  "positions"
-]New value: +[
+  "balances",
+  "positions",
+  "spot",
+  "perp"
+]

changedInput schema / properties / layer / description

Previous value: -"Layer"New value: +"Layer (default hypercore)"

changedInput schema / properties / limit / description

Previous value: -"Rows (default 50, max 500)"New value: +"Rows (default 50)"

changedInput schema / properties / limit / maximum
```
Previous value: -500New value: +1000
```

changedInput schema / properties / token / description

Previous value: -"HyperCore name / coin, or 0x address"New value: +"Token address (Elysium, HyperEVM), token name or perp coin (HyperCore)"

removedInput schema / properties / token / maxLength
```
Removed value: -140
```
removedInput schema / properties / token / minLength
```
Removed value: -1
```

addedInput schema / properties / token / pattern

Added value: +"^([A-Za-z0-9@#:/._+-]{1,64}|0x[0-9a-fA-F]{40}(:0x[0-9a-fA-F]{64})?)$"

removedInput schema / required

Removed value: -[
-  "layer",
-  "token"
-]

First observedOct 21, 2026

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. Beyond that, the description discloses real behavioral traits: system addresses (pools, bridges, launchpad, zero/dead) are counted apart via excludeSystem, named wallets carry `entity`, EVM rows expose labelKind categories, and holders get pnl and behavioral tags with tagShares scoped to 'the 100 largest'. It stops short of stating ordering, pagination, or what an empty result looks like.

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

Conciseness3/5

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

The core purpose is front-loaded, and given the absence of an output schema, enumerating return fields is defensible rather than filler. However, the text is a dense semicolon-and-parenthetical run-on that packs layer semantics, labels, PnL and tags into one block, making it hard to scan for the field an agent actually needs.

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

Completeness4/5

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

With six parameters and no output schema, the description carries the return-value burden and mostly discharges it: concentration/top-10 share, system-address separation, EVM label taxonomy, per-holder PnL and tags, and tagShares/proHolders are all explained. Remaining gaps are ordering, paging past `limit`, and any mention of `network`, which is undocumented here despite being a parameter.

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

Parameters3/5

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

Schema description coverage is 100%, and the description largely restates the schema (layer values, token format per layer, excludeSystem counting). Only the concrete example 'token = name (HYPE)' and the gloss on balances-vs-positions add anything, while `limit` and `network` are untouched. Baseline 3 is appropriate when the schema does the heavy lifting.

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

Purpose4/5

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

The opening clause states a precise verb and resource: 'Largest holders of a token and its concentration (top-10 share…)', plus a scope qualifier that system addresses are counted separately. It does not name or rule out any sibling (e.g. get_holders_history, get_token_traders), so an agent must still infer the split between this and related holder/trader tools.

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

Usage Guidelines3/5

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

Usage is only implied through per-layer invocation notes ('hypercore: token = name (HYPE), kind = balances… hyperevm / elysium: token = 0x address'), which is helpful for calling correctly. There is no explicit when-to-use vs. when-not guidance and no pointer to the sibling that would cover historical holders or trader lists.

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

All Femtos tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?