polymarket-mcp-server

Overview Schema Source Related Servers Discussions Admin

Get Polymarket events

polymarket_get_events

Read-onlyIdempotent

Retrieve Polymarket events that group related markets under a single question. Fetch one event by slug or list top events by 24h volume.

Instructions

Get Polymarket EVENTS, which group related markets under one question (e.g. a tournament or election, with a market per team/candidate).

Use this when a question spans many outcomes: one event carries all its markets. Pass a slug for one event, or omit it for the top events by 24h volume.

Args:

slug (string, optional): event slug for one event with all its markets. If omitted, returns top events.
limit (number): max events when listing, 1-20 (default 5).
active_only (boolean): only open/unresolved events (default true).
response_format ('markdown' | 'json'): default 'markdown'.

Returns: { count, events:[{ slug, title, startDate, endDate, active, closed, volume, liquidity, volume24hr, negRisk, marketCount, markets:[{ question, slug, conditionId, outcomes, volume, closed }] }] }. Errors: "No event found for slug '…'" if the slug is wrong.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`slug`	No	Event slug for a single event with all its markets. If omitted, returns top events by 24h volume.
`limit`	No	Max events when listing (1-20, default 5).
`active_only`	No	Only open / unresolved events (default true).
`response_format`	No	Output format: 'markdown' (concise, human-readable; default) or 'json' (full structured data).	markdown

Output Schema

TableJSON Schema

Name	Required	Description	Default
`count`	Yes
`events`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Sep 28, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld). The description adds real behavioral context on top: default listing behavior (top events by 24h volume when slug is omitted) and the exact error string returned for a bad slug. It doesn't discuss rate limits or pagination, keeping it below 5.

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?

Front-loaded with the resource definition, then usage, args, returns, and errors in a clean scannable structure. The Returns block partially duplicates the existing output schema and the Args block repeats the schema, so a small amount of redundancy keeps it from 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?

For a four-parameter read tool with annotations and an output schema, the description covers purpose, usage, defaults, and error behavior. An agent has everything needed to select and invoke it correctly without further inference.

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%, so the schema already documents all four parameters, including the limit range and response_format enum. The Args block in the description restates these without adding syntax or format detail beyond the schema, so the baseline of 3 is correct.

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?

States a concrete verb+resource (get Polymarket EVENTS) and immediately defines the abstraction: events group related markets under one question. This conceptual definition is exactly what separates it from siblings like polymarket_get_market and polymarket_search_markets, which operate on individual markets.

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

Usage Guidelines4/5

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

Gives explicit when-to-use guidance ('Use this when a question spans many outcomes') and explains the two invocation modes (pass a slug for one event, omit it for top events by volume). It stops short of naming an alternative tool or stating when-not to use it, so it falls just short of a 5.

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