Provides risk assessment for BNB Chain addresses, tokens, and smart contracts, including wallet profiling, token risk checks, contract inspection, and fund tracing.
Provides risk assessment for Ethereum addresses, tokens, and smart contracts, including wallet profiling, token risk checks, contract inspection, and fund tracing.
Provides risk assessment for Polygon PoS addresses, tokens, and smart contracts, including wallet profiling, token risk checks, contract inspection, and fund tracing.
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., "@web3-risk-mcp Is this token a honeypot? 0x2b591e..."
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.
A fraud analyst for web3 that any AI assistant can use.
web3-risk-mcp is an MCP server: a small program that gives AI assistants
(Claude Desktop, Cursor, and other MCP clients) new tools. These tools check a
crypto wallet, token, or smart contract for risk before someone interacts
with it. It then gives a 0–100 risk score with a clear reason for every point.
MCP (Model Context Protocol) is an open standard for connecting AI assistants to outside tools and data. Write a tool once, and every MCP client can use it.
Related MCP server: Crest Counterparty Intelligence
Crypto scams are common, fast, and final. There is no bank to call and no "undo" button. Common traps include:
Honeypot tokens: you can buy them, but the contract stops you from selling.
Rug pulls: the creator removes the trading money (the "liquidity") and the price goes to zero.
Hidden owner powers: the owner can mint new tokens, freeze your wallet, or raise the sell fee to 100%.
Dirty money: a wallet that received funds from a hack or a mixer.
People now ask AI assistants "is this token safe?" Without real data the assistant can only guess. This server gives it real, on-chain evidence from several sources, and a score it can explain line by line.
This is a safety feature, not a missing feature.
The server never... | Why |
asks for a private key or seed phrase | A key gives full control of a wallet. A risk checker has no reason to see one, so any tool that asks for one should be treated as a scam. |
signs or sends transactions | Every check uses public, read-only data. There is no code path that can move funds. The RPC client even refuses any method outside a short read-only allow-list. |
holds funds or approves spending | Nothing to steal, nothing to drain. |
Because of this, it is safe to hand the tools to an AI assistant. The worst a
confused assistant can do is read public data. Every tool is also marked with
the MCP readOnlyHint, so clients know it does not change anything.
Tool | What it answers |
| "How risky is this address?" Detects if it is a wallet, token, or contract, runs the right checks, and returns a 0–100 score with every point explained. |
| Wallet age, balance, number of transactions sent, top counterparties, tokens used recently, activity patterns, who first funded it, and known bad-actor labels. |
| Honeypot signs, mint, blacklist, and pause powers, buy and sell tax, owner and holder concentration, liquidity size, and whether liquidity is locked. |
| Is the source verified? Is it an upgradeable proxy? Who controls it: a single wallet, a multisig, or nobody? Plus a plain-English summary of risky functions. Works on unverified contracts too, by scanning the bytecode. |
| Follows money in and out for 1 or 2 hops and flags links to mixers, sanctioned wallets, exploiters, and phishing addresses, with the full path. |
| The chains it supports. |
Also included:
Resource risk://scoring-method: the full scoring rules, generated from the same rule table the scorer uses.
Prompt investigate_address: a step-by-step investigation plan that tells the assistant which tools to call, what to look for, and how to explain the result to a beginner.
Chains: Ethereum, Base, Arbitrum One, Polygon PoS, and BNB Chain.
flowchart LR
client["MCP client<br/>(Claude Desktop, Cursor)"] -->|"stdio or streamable HTTP"| server["MCP server<br/>6 tools, 1 resource, 1 prompt"]
subgraph analysis["Analysis"]
score["score_risk"]
wallet["wallet profile"]
token["token risk"]
contract["contract inspection"]
trace["fund tracing"]
end
server --> score
score --> wallet & token & contract & trace
wallet & token & contract & trace --> findings["Findings<br/>(id, severity, reason, source)"]
findings --> scorer["Rule-based scorer<br/>0-100 + reasons + confidence"]
wallet & token & contract & trace --> http["Shared HTTP layer<br/>cache, rate limits, retries"]
http --> etherscan["Etherscan V2<br/>history, source code"]
http --> goplus["GoPlus<br/>token and address security"]
http --> dex["DexScreener<br/>pools and liquidity"]
http --> rpc["Public RPC nodes<br/>balance, code, proxy slots"]
wallet & trace --> list["Local list<br/>known mixers and exploiters"]A few design choices worth knowing:
One failing source never breaks an investigation. Each call is wrapped.
If GoPlus is down, you still get the Etherscan and DexScreener results, and
the report lists what failed and why in sources and data_gaps.
Missing data lowers confidence, not the score. A report never quietly treats "no data" as "safe".
Resilient HTTP. Answers are cached (5 minutes by default). Each source has its own rate limit under the free-plan limits. Timeouts, HTTP 429, and server errors are retried with exponential backoff and jitter. API keys are removed from logs, cache keys, and error messages.
Findings, then scoring. The analysis code only describes what it sees. A separate, pure scoring function turns findings into points. This keeps the score easy to test and easy to explain.
You need Python 3.11+ and uv.
git clone https://github.com/MelvTheGoat/web3-risk-mcp.git
cd web3-risk-mcp
uv sync
cp .env.example .env # then add your keysSetting | Where to get it | Needed? |
| etherscan.io/myapikey. One key covers every chain through the V2 API. | Yes, for wallet history, source code, and tracing |
| gopluslabs.io developer dashboard | No. GoPlus works without a key, at lower limits. |
| Any provider, for example Alchemy or Infura | No. Free public nodes are the default. |
DexScreener | No key | – |
Note on Etherscan's free plan. It no longer includes account history on Base and BNB Chain. On those chains the wallet and tracing tools still return balance and contract data from RPC, and they say that history is missing. Source-code lookups work on every chain.
Never commit your .env file. It is already in .gitignore.
uv run web3-risk-mcp # stdio (for local clients)
uv run web3-risk-mcp --transport http --port 8000 # streamable HTTP at /mcpdocker build -t web3-risk-mcp .
docker run --rm -p 8000:8000 --env-file .env web3-risk-mcp # HTTP on :8000/mcp
docker run -i --rm --env-file .env web3-risk-mcp --transport stdio # stdioThe image runs as a non-root user.
Open Settings → Developer → Edit Config and add this to
claude_desktop_config.json. Use the full path to your copy of the repo.
{
"mcpServers": {
"web3-risk": {
"command": "uv",
"args": ["--directory", "/full/path/to/web3-risk-mcp", "run", "web3-risk-mcp"]
}
}
}--directory makes the server start inside the repo, so it finds your .env.
Restart Claude Desktop. The tools appear under the tools icon, and the
investigate_address prompt appears in the prompt menu.
Add the same block to ~/.cursor/mcp.json (all projects) or
.cursor/mcp.json (one project):
{
"mcpServers": {
"web3-risk": {
"command": "uv",
"args": ["--directory", "/full/path/to/web3-risk-mcp", "run", "web3-risk-mcp"]
}
}
}Start the server with --transport http (or the Docker image) and point the
client at http://localhost:8000/mcp:
{ "mcpServers": { "web3-risk": { "url": "http://localhost:8000/mcp" } } }Things you can ask your assistant once the server is connected:
"Is it safe to buy the token 0x… on Base?"
"Who controls the contract 0x…? Can they change it?"
"Where did the money in wallet 0x… come from? Any links to mixers?"
"Give me a risk score for 0x… and explain every point."
Or pick the investigate_address prompt and paste an address.
Below is real output from score_risk for a honeypot-style token. The data
comes from the test fixtures (tests/test_token.py), so the address is a
placeholder. The list is trimmed to the top 7 contributions.
{
"score": 100,
"level": "critical",
"verdict": "Very likely dangerous. Do not interact.",
"confidence": "high",
"address_type": "token",
"contributions": [
{ "finding_id": "token.honeypot", "points": 60, "counted": true,
"reason": "A test sale failed. Buyers of this token are likely unable to sell it.", "source": "GoPlus" },
{ "finding_id": "token.extreme_sell_tax", "points": 45, "counted": true,
"reason": "Selling costs 99.0% of the amount. You would lose most of your money.", "source": "GoPlus" },
{ "finding_id": "token.not_open_source", "points": 25, "counted": true,
"reason": "Nobody can read what this contract really does.", "source": "GoPlus" },
{ "finding_id": "token.mintable", "points": 15, "counted": true,
"reason": "New tokens can be created, which dilutes holders.", "source": "GoPlus" },
{ "finding_id": "token.tax_modifiable", "points": 15, "counted": true,
"reason": "The owner can raise the buy or sell tax at any time.", "source": "GoPlus" },
{ "finding_id": "token.blacklist", "points": 10, "counted": true,
"reason": "The owner can block chosen wallets from selling or moving tokens.", "source": "GoPlus" },
{ "finding_id": "token.insider_holds_large_share", "points": 10, "counted": true,
"reason": "The owner and creator together hold 30.0% of the supply.", "source": "GoPlus" }
],
"points_added": 218,
"points_removed": 0,
"checks_run": ["check_token_risk", "inspect_contract", "address_labels"],
"data_gaps": []
}inspect_contract also writes a plain-English summary. For an unverified
contract owned by one wallet:
This contract's source code is not published, so its behaviour is hidden. The function list below comes from a bytecode scan and may be incomplete. It is owned by a single wallet (0xdede…dede). Functions that could hurt users: it can create new tokens out of thin air, which dilutes every holder; can block chosen wallets from selling or moving tokens.
The score is rule-based and fully explainable. There is no machine learning and no hidden weighting.
Each tool turns what it sees into findings with a stable ID, such as
token.honeypot or trace.direct.mixer.
A public rule table gives each finding ID its points. Trust signals give
negative points: for example token.trusted is −40 and wallet.established is −10.
Findings that describe the same problem share a group, and only the biggest in a group counts. For example, "source not verified" from GoPlus and from Etherscan count once.
The total is clamped to 0–100.
Decisive findings (honeypot, sanctioned address, known exploiter, phishing, fake token, and a few others) set a floor of 75, so trust signals can never hide them.
Score | Level | Meaning |
75–100 | critical | Very likely dangerous. Do not interact. |
50–74 | high | Serious red flags. Avoid unless you fully understand the risks. |
20–49 | medium | Some warning signs. Look closely before interacting. |
0–19 | low | No major red flags in the data we could check. |
Each score also has a confidence (high, medium, or low) based on how many
data sources answered. Every contribution lists its points, its reason, its
source, and the rule that applied. The full rule table is in
docs/risk-method.md, and clients can read it through the
risk://scoring-method resource. Both are generated from the code, and a test
fails if the document drifts.
eval/dataset.json has 34 hand-checked addresses, each
with a source for its label:
12 risky: a honeypot token from a GoPlus case study, the SQUID rug pull, 4 phishing wallets labelled by Etherscan and ScamSniffer, 4 exploiter wallets (Ronin, Bybit, Euler, Wormhole), and 2 Tornado Cash pools.
22 safe: major tokens on all five chains (USDC, USDT, DAI, WETH, UNI, LINK, AAVE, WBTC, stETH, ARB, CAKE, and others), Uniswap and Aave contracts, vitalik.eth, and an exchange hot wallet.
eval/run_eval.py scores every item and reports ROC AUC,
precision, recall, false alarms, and missed items at a threshold of 50. It
runs twice. The second run switches off the local list of known bad
addresses. Six risky items are on that list, so the second run shows what the
other signals (GoPlus, contract analysis, behaviour) catch on their own. This
keeps the evaluation honest.
uv run python eval/run_eval.py --record # live run, saves every API response
uv run python eval/run_eval.py --replay # re-run offline from the saved responsesWith --record, every response is saved to eval/fixtures/cassette.json.gz
(API keys are never stored). Anyone can then reproduce the exact numbers with
--replay, without keys or network access.
Results: pending the first live run. The results table will go here
and in eval/results.md.
Only as good as its sources. A brand-new scam that GoPlus has not scanned and that is not on any list can score low. A low score is "no red flags found", not "safe".
Rule weights are hand-picked. They follow common scam patterns and are checked by the evaluation set, but they are not a trained statistical model.
Sampled history. Wallet profiles and fund tracing look at the latest 100 transactions of each kind (50 for hop-2 addresses), and tracing follows the busiest paths only. Old or low-volume activity can be missed.
Bytecode scanning is a heuristic. It finds known function signatures in unverified contracts. Renamed or custom functions can slip through.
Etherscan free plan. No account history on Base or BNB Chain without a paid plan.
Small local list. The built-in list of known bad addresses is short and hand-checked on purpose. GoPlus provides the broad coverage.
EVM only. No Solana, Bitcoin, or other non-EVM chains.
Not financial advice. This is a research tool. Always do your own checks.
uv sync # install everything, including dev tools
uv run pytest # 100+ tests; all HTTP is mocked, no keys needed
uv run ruff check . # lint
uv run ruff format . # format
uv run python scripts/render_method_doc.py # rebuild docs/risk-method.md after changing rulesCI runs lint, format checks, and tests on Python 3.11, 3.12, and 3.13, and builds the Docker image on every push.
src/web3_risk_mcp/
├── server.py MCP tools, resource, and prompt
├── __main__.py command line (stdio or HTTP)
├── config.py settings from .env
├── chains.py supported chains and address checks
├── services.py builds all API clients
├── clients/ Etherscan, GoPlus, DexScreener, RPC, and the shared HTTP layer
├── analysis/ wallet, token, contract, trace, and score logic
├── scoring.py rule table and scoring function
├── method.py builds the scoring-method document
├── prompts.py investigate_address prompt text
├── labels.py lookup for the local address list
├── evaluation.py metrics and record/replay for the evaluation
└── data/known_addresses.jsonAddress: an account on the blockchain, written as 0x plus 40 hex characters. It can be a wallet or a contract.
Wallet (EOA): an address controlled by a private key held by a person.
Smart contract: a program that lives on the blockchain at its own address.
Token (ERC-20): a coin created by a smart contract.
EVM: the Ethereum Virtual Machine. EVM chains share the same address and contract format.
DEX / pool / liquidity: a decentralized exchange is a contract where people trade tokens. A pool holds two tokens, and the money in it is its liquidity.
LP tokens / locked liquidity: whoever holds a pool's LP tokens can withdraw its liquidity. Locking or burning them stops a rug pull.
Honeypot: a token you can buy but cannot sell.
Proxy / upgradeable contract: a contract whose logic can be swapped for new code by its admin.
Renounced: the owner gave up control, so owner-only functions can no longer be used.
Multisig: a wallet that needs several people to sign, which is safer than a single key.
Mixer: a service that pools and mixes funds to hide where they came from.
Verified source: the author published the source code and the block explorer confirmed it matches the code on chain.
Function selector: a 4-byte fingerprint of a function's name and inputs, stored in the contract's bytecode.
Check an ERC-20 token for scam signs before buying it: honeypot (cannot sell), mint, blacklist, and pause powers, buy/sell tax, owner and holder concentration, liquidity size, and whether liquidity is locked.
| Name | Required | Description | Default |
|---|---|---|---|
| chain | No | Chain name or ID: ethereum, base, arbitrum, polygon, or bsc. | ethereum |
| token_address | Yes | An EVM address: 0x followed by 40 hex characters. |
| Name | Required | Description |
|---|---|---|
| name | No | |
| chain | Yes | |
| pools | No | |
| taxes | No | |
| powers | No | |
| symbol | No | |
| address | Yes | |
| sources | No | |
| findings | No | |
| is_proxy | No | |
| data_gaps | No | What we could not check. Missing data is not proof of safety. |
| owner_pct | No | |
| creator_pct | No | |
| is_honeypot | No | True if the token can be bought but not sold. |
| top_holders | No | |
| holder_count | No | |
| liquidity_usd | No | |
| lp_locked_pct | No | Share of pool (LP) tokens locked or burned, so liquidity cannot be pulled. |
| on_trust_list | No | |
| owner_address | No | |
| is_open_source | No | |
| creator_address | No | |
| owner_renounced | No | True if the owner gave up control by setting it to a dead address. |
| top10_holder_pct | No | Top 10 wallets' share, not counting burn, locked, or pool addresses. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that the tool is read-only and non-destructive, so the description does not need to restate that. It adds value by detailing exactly what the risk check covers, including honeypot detection, mint/blacklist/pause powers, taxes, and liquidity lock status. There is no contradiction with the annotations.
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 dense sentence with the purpose front-loaded and a compact, colon-separated list of checks. There is no filler, no repetition of schema fields, and no redundant safety language.
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 an output schema present, the description does not need to describe return values. The annotations, the fully documented schema, and the description together provide everything needed to invoke the tool correctly: when to use it, what address to provide, and what risk factors are evaluated.
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 chain and token_address are already documented in the schema. The description adds one useful semantic cue: token_address should point to an ERC-20 token, not just any EVM address, and the tool is framed as pre-purchase due diligence.
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-resource pair ('Check an ERC-20 token for scam signs') and then enumerates concrete risk dimensions: honeypot, mint, blacklist, pause powers, taxes, holder concentration, and liquidity. This makes the tool's scope obvious and separates it from generic siblings like inspect_contract or score_risk.
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 phrase 'before buying it' gives a clear, practical context for when an agent should call this tool. However, it does not explicitly name alternatives or say when not to use it, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe a wallet: age, balance, transaction count, top counterparties, tokens it used recently, activity patterns, and any known bad-actor labels.
| Name | Required | Description | Default |
|---|---|---|---|
| chain | No | Chain name or ID: ethereum, base, arbitrum, polygon, or bsc. | ethereum |
| address | Yes | An EVM address: 0x followed by 40 hex characters. |
| Name | Required | Description |
|---|---|---|
| chain | Yes | |
| address | Yes | |
| sources | No | |
| activity | No | |
| findings | No | |
| data_gaps | No | What we could not check. Missing data is not proof of safety. |
| is_contract | No | |
| known_label | No | |
| native_symbol | Yes | |
| recent_tokens | No | |
| native_balance | No | |
| security_flags | No | Bad-behaviour labels reported by GoPlus. |
| first_funded_by | No | |
| transactions_sent | No | Exact number of transactions this address has sent (its nonce). |
| top_counterparties | No | |
| first_funded_by_label | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral context such as data source caveats, potential incompleteness, or external label reliability; openWorldHint covers some of this implicitly, but the description itself contributes nothing beyond the output field list.
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 focused sentence that front-loads the core action and then lists concrete output facets. The list is slightly long but every item adds value, 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?
The presence of an output schema covers return-value details, and annotations cover safety and open-world assumptions. The main gap is the lack of explicit sibling differentiation, but for a read-only descriptive tool the definition is otherwise 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?
Schema coverage is 100%, so both parameters are already well-documented in the schema. The description does not add parameter-level detail, which is acceptable but not additive. Baseline 3 is appropriate when the schema already handles parameter semantics.
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 verb 'Describe' and the resource 'a wallet', then enumerates the exact output categories (age, balance, transaction count, top counterparties, tokens, activity patterns, bad-actor labels). This clearly distinguishes it from the risk-scoring siblings (score_risk, check_token_risk) which evaluate rather than describe.
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 retrieving a descriptive wallet profile, but it does not explicitly state when to choose it over alternatives like score_risk or trace_funds. There is no mention of when not to use it or which sibling handles related use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect a smart contract: is the source verified, is it an upgradeable proxy, who owns or controls it (wallet, multisig, or renounced), and a plain-English summary of risky functions such as mint, blacklist, pause, and fee changes.
| Name | Required | Description | Default |
|---|---|---|---|
| chain | No | Chain name or ID: ethereum, base, arbitrum, polygon, or bsc. | ethereum |
| contract_address | Yes | An EVM address: 0x followed by 40 hex characters. |
| Name | Required | Description |
|---|---|---|
| chain | Yes | |
| owner | No | |
| proxy | No | |
| address | Yes | |
| creator | No | |
| license | No | |
| sources | No | |
| summary | No | |
| findings | No | |
| verified | No | |
| data_gaps | No | What we could not check. Missing data is not proof of safety. |
| created_at | No | |
| creation_tx | No | |
| is_contract | No | |
| contract_name | No | |
| risky_functions | No | |
| compiler_version | No | |
| bytecode_size_bytes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description has a lower burden for side-effect disclosure. It adds value by stating exactly what information the call surfaces: verification status, proxy status, ownership, and risky-function summaries. No contradiction with the annotations.
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?
A single sentence that front-loads the verb and object ('Inspect a smart contract') and then lists the queries it answers. Every clause carries substantive information and there is no filler, but the density of the list makes it slightly less scannable than a two-sentence structure.
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 an output schema present, the description need not enumerate return fields; it already conveys the high-level answers the tool provides. The only gap is the lack of explicit routing guidance among sibling tools, but the strong purpose clarity and well-documented schema make the tool fully invokable.
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%: both chain and contract_address already have clear descriptions in the schema. The description adds no new parameter semantics; it only hints at the tool's overall purpose. This matches the baseline of 3 when the schema fully documents the parameters.
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+resource ('Inspect a smart contract') and then enumerates exact outputs: verification status, proxy status, owner/control type, and high-risk function summaries. These specifics distinguish it from sibling tools like score_risk or check_token_risk, even without naming them.
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 no explicit 'when to use' or 'when not to use' guidance, nor does it name alternatives like score_risk or check_token_risk. Usage is only implied by the contract-inspection context, leaving an agent to infer when this tool is preferred over its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the chains this server can investigate.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| chains | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds modest value by framing the result as the set of chains 'this server can investigate,' clarifying the list's purpose. It does not contradict annotations.
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?
A single front-loaded sentence with zero filler. Every word earns its place, and the verb 'List' leads immediately.
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 zero-parameter listing tool with an output schema (covering return values) and annotations covering safety behavior, the description is nearly complete. The only minor gap is that it doesn't note the open-world nature of the result set, but openWorldHint already communicates that via annotations.
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 tool has zero parameters and schema coverage is 100%, so the baseline is 4. The description adds no parameter detail, and none is needed since there is nothing to configure.
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 a specific verb and resource: 'List the chains this server can investigate.' The phrase 'this server can investigate' also conveys scope, distinguishing it naturally from the sibling analysis tools (score_risk, inspect_contract, trace_funds), which act on chains rather than enumerating them.
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?
No explicit when-to-use or alternative routing, but the usage context is clearly implied: since the sibling tools investigate chains, an agent can infer this tool should be queried first to discover which chains are eligible for investigation. Adequate for a zero-parameter capability-discovery tool, though it never states 'call this before chain-specific tools.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Give an address a 0-100 risk score with a reason for every point.
Works for wallets, tokens, and other contracts: it detects the type and runs
the matching checks. The result lists each finding, its points, and its source,
plus a confidence level and anything that could not be checked.
| Name | Required | Description | Default |
|---|---|---|---|
| chain | No | Chain name or ID: ethereum, base, arbitrum, polygon, or bsc. | ethereum |
| address | Yes | An EVM address: 0x followed by 40 hex characters. | |
| include_trace | No | Also trace funds one hop out (wallets only). Slower. |
| Name | Required | Description |
|---|---|---|
| chain | Yes | |
| level | Yes | |
| score | Yes | |
| method | No | |
| address | Yes | |
| sources | No | |
| verdict | Yes | |
| data_gaps | No | |
| checks_run | Yes | |
| confidence | Yes | |
| address_type | Yes | |
| points_added | Yes | |
| contributions | Yes | |
| points_removed | Yes | |
| decisive_floor_applied | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context: it detects the type, runs matching checks, returns per-finding points and sources, includes confidence, and discloses that some checks may not be possible. This goes beyond the annotations without contradicting them.
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 sentences, no filler. The first sentence states the core purpose immediately, and the second summarizes output details. Every clause earns its place and there is no redundant restating of the name.
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 output schema already exists, the description need not explain return values in depth, yet it still covers the key behavioral aspects: scoring range, reason coverage, supported address types, and transparency about uncheckable items. Nothing essential to calling the tool correctly 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 all three parameters (chain, address, include_trace) are already documented in the schema. The tool description adds no parameter-specific guidance, but the schema carries the full load, making the baseline 3 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 opens with a specific verb and resource: 'Give an address a 0-100 risk score with a reason for every point.' It clearly distinguishes itself from narrower siblings by stating it works for wallets, tokens, and other contracts, with type detection. An agent can immediately tell this is the general-purpose risk scoring tool.
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 for any EVM address type ('Works for wallets, tokens, and other contracts') and that type detection routes to the right checks, but it never explicitly names alternatives like check_token_risk or get_wallet_profile, nor states when NOT to use this tool. Usage is implied rather than explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Follow money in and out of an address for 1 or 2 hops and flag links to known risky addresses such as mixers, sanctioned wallets, and exploiters.
| Name | Required | Description | Default |
|---|---|---|---|
| hops | No | How far to follow: 1 or 2. | |
| chain | No | Chain name or ID: ethereum, base, arbitrum, polygon, or bsc. | ethereum |
| address | Yes | An EVM address: 0x followed by 40 hex characters. | |
| direction | No | in = where money came from, out = where it went. | both |
| max_per_hop | No | How many counterparties to follow per step. |
| Name | Required | Description |
|---|---|---|
| hops | Yes | |
| chain | Yes | |
| edges | No | |
| nodes | No | |
| address | Yes | |
| sources | No | |
| findings | No | |
| data_gaps | No | What we could not check. Missing data is not proof of safety. |
| direction | Yes | |
| risky_links | No | |
| native_symbol | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and non-destructive. The description adds useful behavioral context by capping traversal at 2 hops and explaining that it surfaces links to mixers, sanctioned wallets, and exploiters. There is no contradiction with the annotations, and the added risk-flagging behavior goes beyond the minimal safety signal.
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 sentence that front-loads the core action, then efficiently packs in the hop limit and risky-address flagging behavior. There is no filler, no restatement of the tool name, and every clause adds meaningful 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?
For a tool with five parameters, an output schema, and supporting annotations, the description covers the essential purpose and behavior well. It does not explain output structure, but that is unnecessary because an output schema exists. An explicit usage distinction from sibling tools would make it fully complete.
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 address, hops, chain, direction, and max_per_hop are already documented. The description reinforces the concept of following money and hop limits but does not add parameter-level detail beyond the schema, placing it at the baseline.
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 an active verb ('Follow') with a specific resource ('money in and out of an address') and defines the tool's scope ('1 or 2 hops'). It also clearly names the distinctive outcome ('flag links to known risky addresses'), which sets it apart from generic wallet/profile or token-risk 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?
The tracing behavior implies when to use it, such as investigating fund movement or the source/destination of funds. However, the description does not explicitly state when to prefer this over score_risk, check_token_risk, or get_wallet_profile, and it gives no exclusions or prerequisites.
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.
v0.1.0check_token_riskget_wallet_profileinspect_contractlist_supported_chainsscore_risktrace_fundsScored across 6 tools
Most tools are clearly distinct: scoring, profiling, token-specific checks, contract inspection, tracing, and chain listing. However, 'score_risk' and 'check_token_risk' have some overlap when applied to tokens (score_risk already checks tokens, though with a different focus). The descriptions help, but a user might hesitate between the two for a token risk check.
Tools mostly follow a verb_noun pattern: score_risk, get_wallet_profile, check_token_risk, inspect_contract, trace_funds. 'list_supported_chains' is consistent. Minor deviation: 'get_wallet_profile' uses 'get' while others use 'check'/'inspect'/'trace', but it's still a clear verb-noun structure. No mixed casing or vague verbs.
With 6 tools, the server is well-scoped for a blockchain risk investigation tool. Each tool addresses a distinct aspect (scoring, profiling, token safety, contract inspection, fund tracing, chain support). This is within the ideal 3-15 range and feels neither sparse nor bloated.
The toolset covers the full risk investigation lifecycle: get a risk score, profile an address, dive into token-specific risks, inspect contract details, trace fund flows, and list chains. A minor gap: there's no direct function to compare multiple addresses or to get a detailed report on a specific transaction or a custom investigation path, but agents can combine these tools to achieve those outcomes.
Read-only smart-contract security intelligence for autonomous agents.
Crypto security, honeypot detection, wallet analysis, and token risk scoring across 31 blockchains.
DeFi safety layer for AI agents: wallet safety, token risk, tx decode/simulate. 20 tools.
Solana address risk grades and token scans for AI agents. Pay-per-call via x402 (USDC on Base).
