mcp-server-polymarket

Overview Schema Source Related Servers Discussions Admin

List events

list_events

Read-onlyIdempotent

Browse Polymarket events sorted by 24h volume, filter by tag, status, liquidity, dates, or live sports, and preview markets per event.

Instructions

Browse events, sorted by 24h volume by default. Each event lists its top markets; use get_event for all of them.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_events"
  }
}

Input Schema

Name	Required	Description	Default
`live`	No	Only events in play now (sports).
`limit`	No	Rows per page.
`order`	No		volume_24h
`cursor`	No	next_cursor from the previous page. Empty starts at the top.
`status`	No		open
`featured`	No
`tag_slug`	No	e.g. politics, crypto, sports.
`ascending`	No
`end_after`	No	ISO 8601 time, e.g. 2026-11-01 or 2026-11-01T12:00:00Z, or epoch seconds.
`series_id`	No	Only events of this series.
`end_before`	No	ISO 8601 time, e.g. 2026-11-01 or 2026-11-01T12:00:00Z, or epoch seconds.
`min_volume`	No
`max_markets`	No	Markets to include per event.
`title_search`	No	Substring of the title.
`min_liquidity`	No
`include_archived`	No	Also list archived events (slower, offset paging).

Output Schema

Name	Required	Description	Default
`note`	No
`count`	No
`items`	No
`has_more`	No
`next_cursor`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 11, 2026

TDQS

A3.5/5.0

Behavior3/5

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

Annotations already declare this a read-only, idempotent, non-destructive open-world read, so the safety profile is covered. The description adds real context beyond that: results default to 24h-volume ordering and each event embeds only its top markets, which explains why a follow-up get_event call may be needed. It says nothing about pagination behavior or the documented slow path for archived events, so it is additive but not thorough.

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

Conciseness5/5

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

Two short sentences with no filler; the default sort is front-loaded and the get_event hand-off follows immediately. Nothing is repeated from the schema or annotations.

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

Completeness3/5

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

For a 16-parameter discovery tool, the description covers only default ordering and the embedded-markets shape, leaving the entire filtering surface (status, live, tags, series, date and volume bounds, archived inclusion) undocumented. The presence of annotations and an output schema lowers the burden, but an agent still has to read the schema to understand what this tool can actually do.

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?

With 63% schema description coverage across 16 parameters, the schema carries most of the load; several parameters (order, status, featured, min_volume, min_liquidity, ascending) have no description text at all. The definition clarifies the default sort key and that max_markets controls how many markets are embedded per event, but it does not explain status scoping, live, tag_slug, or the volume/liquidity thresholds, so it only partially compensates for the coverage gap.

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?

States a specific verb and resource ("Browse events") plus the default ordering, and distinguishes itself from the sibling get_event by noting each row carries only top markets. It stops short of naming the resource universe (markets/tags/series) that the sibling list_* tools cover, so differentiation is partial rather than complete.

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?

"Browse events" implies a discovery use case, and the definition gives one explicit routing rule: go to get_event when you need all markets for an event. There is no guidance on when to prefer this over list_markets, list_series, or list_tags, nor any mention of the filtering dimensions (status, live, tag, volume thresholds) that would tell an agent which scenarios this tool fits.

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

Deploy Server