Skip to main content
Glama
Sign In
mcp-server-polymarket

mcp-server-polymarket

by tukorama
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

List public Perps fills

list_perps_public_fills
Read-onlyIdempotent

Retrieve a Perps account's public fill history with prices, sizes, fees and realized PnL, paginated at 100 fills and filterable by time, instrument or open position.

Instructions

Fill history of a Perps account: prices, sizes, fees and realised PnL, 100 per page.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "address": "<address>"
    },
    "name": "list_perps_public_fills"
  }
}

Input Schema

NameRequiredDescriptionDefault
endNoISO 8601 time, e.g. 2026-11-01 or 2026-11-01T12:00:00Z, or epoch seconds.
startNoEmpty means 30 days ago.
cursorNonext_cursor from the previous page. Empty starts at the top.
addressYes
oldest_firstNo
instrument_idNoRequired for current_position.
current_positionNoOnly fills of the open position cycle on instrument_id.

Output Schema

NameRequiredDescriptionDefault
noteNo
countNo
itemsNo
has_moreNo
next_cursorNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

B3.3/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds one genuinely new behavioral fact – a fixed page size of 100 – but says nothing about the default 30-day window, rate limits, or whether only public/eligible accounts are addressable.

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?

A single front-loaded sentence that lists the resource, the returned fields, and the page size with zero filler. Nothing could be removed without losing information.

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?

An output schema exists, so return-value explanation isn't required, but for a 7-parameter paginated history tool the definition omits the filtering semantics and default time window an agent needs to call it correctly. Adequate but with clear gaps.

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 coverage is 71%, so most parameters are already documented, and the description adds only the page-size detail beyond it. It does not clarify the default 30-day start behavior, cursor paging across the 100-row pages, or the current_position/instrument_id dependency, leaving the marginal value modest.

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?

The description names a specific resource – fill history of a Perps account – and enumerates the payload fields (prices, sizes, fees, realised PnL), so an agent knows exactly what it gets back. It doesn't explicitly distinguish itself from the closely-named list_perps_trades sibling, leaving that differentiation to inference.

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

Usage Guidelines2/5

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

There is no guidance on when to use this versus list_perps_trades or list_activity, and nothing explains the interaction between current_position and instrument_id (which the schema notes is 'required for current_position'). The agent must reverse-engineer the correct usage scenario.

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

Deploy Server

Other Tools