Nansen

by io.github.hurcanNansen

Looking up prediction market

prediction_market_lookup

Search Polymarket for events and markets by name, topic, URL, or slug.

PM building blocks:

An event is a grouped prediction topic containing many child markets.
A market is one tradable outcome with its own marketId.
Example: 2026 NCAA Tournament Winner is an event; Will Duke win the 2026 NCAA Tournament? is a market. Detail tools require marketId, not eventId.

When to use:

First tool when the user asks about a specific PM topic, event, slug, or Polymarket URL but does not provide marketId.
Optionally provide queryVariant as a cleaner short keyword version.
Set includeEventMarkets to true to also return child markets for the best-matching event.
Do NOT use general_search for prediction markets.
Results include current outcome prices, last trade price, and bid/ask inline — for a quick probability check you may not need prediction_market_ohlcv. For price history or dated moves, still use prediction_market_ohlcv.

Query tips:

Uses Polymarket's search API — natural language queries work well.
Prefer short 1–3 keyword queries for best results.
Avoid broad multi-topic queries like bitcoin ethereum politics.

Output rules:

If lookup returns no suitable market or a mismatched timeframe, say so explicitly — do not silently substitute a nearby market.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`request`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

TDQS

A4.8/5.0

Behavior5/5

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

With no annotations, the description carries full burden of behavioral disclosure. It explains the underlying search API, what results include (current outcome prices, last trade price, bid/ask), and establishes an explicit output rule: 'do not silently substitute a nearby market.' It also notes the behavior of includeEventMarkets regarding count display, providing rich behavioral context.

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?

The description is well-structured with clear sections (PM building blocks, When to use, Query tips, Output rules) and uses bullets for readability. It is longer than some, but every section earns its place given the tool's complexity. Slight over-length prevents a 5.

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?

Given the tool's complexity and the absence of annotations, the description covers all essential aspects: what the tool does, how to use it, when to use alternatives, query formatting tips, result contents, and output rules. An output schema exists to explain return values, so the description is complete for invocation and expectation-setting.

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

Parameters4/5

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

Schema description coverage is 0% for the top-level request parameter, but nested property descriptions exist. The description compensates by clarifying what 'request' can be (name, topic, URL, slug), explaining queryVariant as a 'cleaner short keyword version', and describing includeEventMarkets's effect. It does not mention page, status, maxCandidates, or maxEventMarkets, but the schema covers those, so the added value is meaningful.

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

Purpose5/5

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

The description opens with a clear, specific statement: 'Search Polymarket for events and markets by name, topic, URL, or slug.' It defines events vs. markets and distinguishes itself from siblings by explicitly warning against general_search and referencing prediction_market_ohlcv for price history. This fully clarifies its unique purpose.

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?

Gives explicit when-to-use guidance: 'First tool when the user asks about a specific PM topic, event, slug, or Polymarket URL but does not provide marketId.' Also provides exclusions and alternatives: 'Do NOT use general_search for prediction markets' and 'For price history or dated moves, still use prediction_market_ohlcv.' This is exemplary.

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

All Nansen tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A3.8/5.0

Disambiguation5/5

Each tool has a clearly defined purpose, and overlapping tools (e.g., token_flows vs token_recent_flows_summary, nansen_score_top_tokens vs token_discovery_screener) include explicit guidance on when to use them. Even with similar names like prediction_market_trades and prediction_market_address_trades, the descriptions and parameters make the distinction unambiguous.

Naming Consistency4/5

Most tools follow a domain_prefix_noun pattern (address_, token_, prediction_market_), making them predictable within families. However, outliers like general_search, growth_chain_rank, hyperliquid_leaderboard, and transaction_lookup break the pattern, and some names are long or inconsistently formatted (e.g., smart_traders_and_funds_perp_trades vs smart_traders_and_funds_token_balances).

Tool Count3/5

With 38 tools, the server is far above the typical 3-15 range, making it heavy for agents to navigate. However, Nansen is a broad analytics platform covering wallets, tokens, prediction markets, and smart money activity, so the high count is justifiable as each tool serves a distinct function.

Completeness5/5

The tool set provides comprehensive coverage across token analysis (ohlcv, trading, holders, flows, PnL, technicals), wallet analysis (portfolio, transactions, counterparties), prediction markets (lookup, orderbook, trades, PnL), and discovery. The only obvious omission is NFT support, but it is explicitly documented as out of scope, so no critical dead ends exist.

Resources

Need Help?