polymarket-mcp-server

Overview Schema Source Related Servers Discussions Admin

Find Polymarket arbitrage

polymarket_find_arbitrage

Read-onlyIdempotent

Scan Polymarket binary markets and negRisk event baskets for fee-aware, depth-aware arbitrage gaps where combined best asks fall below $1.

Instructions

Scan for risk-free pricing gaps: a binary market whose best-ask(YES)+best-ask(NO) < $1, or a negRisk event basket whose Σ best-ask(legs) < $1. Fee-aware (reports gross AND net-of-fee edge) and depth-aware (estimates executable size). This is the one edge a read-only bot can DETECT precisely — but detection is not capture.

Args:

event_slug (string, optional) OR scan_top (1-25): scan one event, or sweep the top-N events by 24h volume.
min_edge_pct (number, default 0.5): only flag arbs whose NET edge% ≥ this.
category ('crypto'|'sports'|'politics'|'macro'|'geopolitics'|'other'): taker-fee assumption (geopolitics free).
max_legs (number, default 12): skip baskets larger than this.

Returns: { scanned, feePerShare, category, count, arbs:[{ type, title, legs, grossEdge/Pct, netEdge/Pct, executable:{sets,notionalUsd,estNetProfitUsd,bottleneckLeg} }] }.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`category`	No	Taker-fee assumption bucket (geopolitics = free).	other
`max_legs`	No	Skip baskets larger than this many legs (default 12).
`scan_top`	No	Sweep the top-N events by 24h volume. Provide this OR event_slug.
`event_slug`	No	Scan one event's negRisk basket + its binary markets. Provide this OR scan_top.
`min_edge_pct`	No	Only flag arbs whose NET edge (after fees) ≥ this % (default 0.5).
`response_format`	No	Output format: 'markdown' (concise, human-readable; default) or 'json' (full structured data).	markdown

Output Schema

TableJSON Schema

Name	Required	Description	Default
`arbs`	Yes
`count`	Yes
`scanned`	Yes
`category`	Yes
`feePerShare`	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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: it is fee-aware (gross AND net-of-fee edge), depth-aware (estimates executable size, bottleneck leg), and warns that detection does not equal capture. That is meaningful disclosure beyond structured fields.

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 detection condition, then cleanly split into Args and Returns sections. The one prose flourish ('the one edge a read-only bot can DETECT precisely') earns its place as routing context, though the Returns block partly duplicates the output schema.

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 read-only, zero-required-param scan tool with an output schema and full annotation coverage, the description supplies both argument semantics and the shape of the returned edge objects (gross/net edge, executable size, bottleneck leg). Nothing an agent needs to invoke or interpret it is missing.

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 six parameters, including the fee bucket, the OR relationship, and defaults. The description largely restates these in prose (event_slug/scan_top, min_edge_pct default 0.5, category, max_legs default 12) without adding syntax or edge-case semantics beyond what the schema says. Baseline 3 applies.

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 states a specific verb and resource ('Scan for risk-free pricing gaps') and then defines the exact mathematical condition it detects: best-ask(YES)+best-ask(NO) < $1 or a negRisk basket whose Σ best-ask(legs) < $1. This is so specific that it self-distinguishes from every sibling, which are generic getters or paper-trading tools.

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?

It gives the operative choice condition explicitly: 'scan one event, or sweep the top-N events by 24h volume', mirrored by the event_slug OR scan_top params. The closing 'detection is not capture' implicitly points the agent at the paper-trading siblings for execution, but it never names them or states exclusions, so it falls short of a full when/when-not routing rule.

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