Summary: This server gives historical Polymarket order book depth and market data over MCP — the L2 ladders that Polymarket itself does not archive — plus search, pricing, and market-quality metrics.
Search recurring market series, related event groups, and individual markets by keyword/date.
Get full market details including outcome token IDs, resolution status, and the winning outcome.
Retrieve historical L2 bid/ask order book depth at 1-second to 1-day resolution, with pagination for large windows.
Get per-outcome-token price history aligned to the same timeline, finer than Polymarket's free 1-minute data.
Get derived market quality metrics: spread, liquidity, and volume over time.
Check your plan, rate limits, quota, and available history window.
Works via an MCP client using npx and a free API key; it does not provide live odds or trade execution.
Historical Polymarket order book depth for Claude, Cursor and any other MCP client — full L2 bid and ask ladders at 1-second resolution, with resolved outcomes attached.
Polymarket's own API serves price history well. It does not archive order
book depth at any granularity — /book returns the current state and nothing
stores it. This server exposes depth that was captured live, which is the part
that cannot be recovered after the fact.
Nothing to install. Add it to your MCP client config and it runs via npx.
Claude Desktop — claude_desktop_config.json:
{
"mcpServers": {
"polyorderbooks": {
"command": "npx",
"args": ["-y", "@polyorderbooks/mcp-server"],
"env": { "POLYORDERBOOKS_API_KEY": "pob_..." }
}
}
}Cursor — .cursor/mcp.json, same shape.
Restart the client after editing the config; MCP servers are started at launch.
Related MCP server: polymarket-mcp-server
Sign up at polyorderbooks.com/signup. No card is required.
Open the dashboard and create a key. It looks like pob_ followed by a long
random string.
Put it in the env block of your MCP client config, as above.
The free Starter plan queries at 1-second resolution — the same as the paid plans. What the paid plans add is a longer history window and a higher request allowance, not finer data. Starter is enough to answer a real question before you decide whether to pay for anything.
Call the get_usage tool at any time to see the plan, limits and remaining
allowance on the key you configured.
Variable | Required | Purpose |
| yes | Your API key. The server exits at startup if this is missing, rather than failing later on the first tool call. |
| no | Overrides the API base URL. Defaults to |
Set these in the MCP client config, not in your shell. A client launches the
server as a subprocess and does not pass your interactive shell environment to
it, so a key exported in .zshrc will not be visible to the server.
Tool | What it does |
| Recurring families — |
| Groups of markets that resolve together. |
| Individual markets by keyword or date range. |
| One market in full, including outcome tokens and the winner. |
| L2 ladders over time. The thing Polymarket does not archive. |
| Price series per outcome token. |
| Spread, liquidity and volume as a time series. |
| Plan, rate limits and quota. |
The catalogue is series → events → markets. Ask for a kind of market with
search_series, a set that resolves together with search_events, and a
specific one with search_markets.
Books go one-sided as markets resolve. In the final minute of a 5-minute market, 76% of snapshots have an empty bid or ask side — nobody offers the losing outcome. This is real market behaviour, not missing data, and it breaks analysis that assumes two-sided books.
Contract length changes everything. A 4-hour contract is one-sided 0.5% of the time; a 5-minute contract, 17%. Conclusions from one do not transfer to the other.
Responses get large quickly. An hour at 1-second resolution is 3,600 buckets
per token, and a market has two. Keep windows narrow or resolution coarse, and
page with the returned next_cursor.
Find BTC 5-minute markets that resolved yesterday and show me how the order book depth changed in the final two minutes before settlement.
For this market, what would a 100-share buy have cost against the actual ladder five seconds before close, versus the midpoint at that moment?
Compare spread and liquidity across 5-minute, 15-minute and 4-hour BTC contracts over the last day.
The second one is the point of L2 data. A price series tells you where the market was; only the ladder tells you what you could have traded at.
Several good ones exist — kukapay/polymarket-predictions-mcp, demwick/polymarket-agent-mcp, PaulieB14/graph-polymarket-mcp. They wrap Polymarket's own Gamma and CLOB APIs and do it well.
Those | This one | |
Live odds and current book | yes | no |
Placing trades | some | no |
Market metadata and resolution | yes | yes |
Price history | 1-minute, from Polymarket | 1-second |
Historical order book depth | not available | yes |
The difference is structural rather than a matter of effort. Polymarket's /book
endpoint returns the present state and nothing archives it, so no server built on
that API can serve yesterday's ladders. This one reads an archive that was
captured live.
If you want to trade, or want live odds, use one of theirs — they cover that better. Use this when the question is about what the book looked like at a specific past moment.
"POLYORDERBOOKS_API_KEY is not set" — the key is missing. It goes in the env
block of the client config, not your shell. See
Environment variables.
Authentication failed — the key reached the server but the API rejected it.
Keys start with pob_; check for a trailing newline or a stray quote if you
pasted from a terminal. If it looks right, call get_usage to confirm the key is
active.
Responses truncated or slow — an hour at 1-second resolution is 3,600 buckets
per token, and a market has two. Narrow the window, or use resolution: "1m" and
page with next_cursor.
Empty ladders — expected near settlement. See the note above on one-sided books.
897,192 snapshots across 805 resolved markets and three contract lengths are published under CC BY 4.0 with a DOI, no signup:
doi.org/10.5281/zenodo.22084114
Useful for checking the properties above yourself before relying on the API.
npm install
npm run build
POLYORDERBOOKS_API_KEY=pob_... npm run devThe server speaks stdio. To exercise it without an MCP client, send JSON-RPC on
stdin — initialize, then tools/list, then tools/call.
polyorderbooks.com — the API
docs.polyorderbooks.com — reference
Python client — pip install polyorderbooks
Free BTC sample — one market, no signup
MIT. Not affiliated with, endorsed by, or connected to Polymarket.
Full detail for a single market by slug or id, including its outcome tokens, resolution status and winning outcome. Use this to get token ids before calling the token-level tools.
| Name | Required | Description | Default |
|---|---|---|---|
| id_or_slug | Yes | Market slug, e.g. btc-updown-5m-1787551200 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure. It indicates this is a retrieval operation and specifies what the response contains: outcome tokens, resolution status, and winning outcome. This is sufficient for a simple read-only market-detail tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: one states what the tool returns, the other states when to use it. No repetition, no filler, and useful context is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter getter with no output schema, the description covers the important contents and a concrete downstream use. It could also mention using search_markets when the slug is unknown, but that is not essential because the tool's scope is otherwise well specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes id_or_slug with an example, so the baseline is 3. The description adds only the clarification 'or id', which is helpful but not substantial beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb and resource: getting full detail for a single market by slug or id. It also enumerates what is included, so it is easy to distinguish from search_markets and the other sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit use case: call this tool to get token ids before using token-level tools. It does not explicitly say when not to use it or point to search_markets for discovering a slug, but the simple single-market context makes the intended usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Derived market quality metrics — spread, liquidity and volume — as a time series. Cheaper than pulling full order books when the question is about market quality rather than specific price levels. Note that spread is only meaningful while both sides of the book are populated, which stops being true near settlement.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Default 100, max 200 | |
| cursor | No | ||
| end_ts | Yes | ISO-8601 UTC, e.g. 2026-08-23T14:00:00Z | |
| start_ts | Yes | ISO-8601 UTC, e.g. 2026-08-23T14:00:00Z | |
| id_or_slug | Yes | Market slug | |
| resolution | No | Defaults to 1m |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the metrics are derived, cheaper than order-book retrieval, and that spread validity is conditional on both order book sides being populated. The settlement caveat adds beyond the title, but it does not mention pagination behavior or response format beyond 'time series', still leaving a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first presents what it does, second adds the use-case distinction and an important caveat. No filler or redundant restatement of the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite six parameters and no output schema, the description clearly conveys the expected output type (time series of metrics) and the main usage condition. Given the schema supplies high parameter coverage, the only missing part is pagination/cursor semantics, which the schema's 'cursor' field already hints at. Overall adequate, but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, so the schema already documents most parameters well. The description adds meaningful context about what the returned metrics refer to (spread, liquidity, volume), but does not explain specific parameter details like cursor or limit beyond what schema says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb and object: it gets derived market quality metrics (spread, liquidity, volume) as a time series. It also distinguishes itself from the order-book sibling by saying it is cheaper than pulling full order books, making its scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use: 'when the question is about market quality rather than specific price levels' and contrasts with the costlier 'full order books' alternative. It also provides a specific caution about spread near settlement, which acts as a when-not-to-trust boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full L2 bid and ask ladders over time for a market — every price level and the size resting at each. This is data Polymarket does not archive: its /book endpoint returns only the current state, so depth exists only where it was captured live.
One thing to expect when reading the results: binary markets go one-sided as they resolve. In the final minute of a 5-minute market most snapshots have an empty bid or ask side, because nobody offers the losing outcome. That is real market behaviour rather than missing data, so guard before indexing the first level of a ladder.
Responses are large. Keep the window narrow or the resolution coarse: a one-hour window at 1s is 3,600 buckets per token, and a market has two tokens.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Buckets per page, default 50. Use the returned next_cursor to page. | |
| cursor | No | next_cursor from a previous response | |
| end_ts | Yes | ISO-8601 UTC, e.g. 2026-08-23T14:00:00Z | |
| start_ts | Yes | ISO-8601 UTC, e.g. 2026-08-23T14:00:00Z | |
| id_or_slug | Yes | Market slug, e.g. btc-updown-5m-1787551200 | |
| resolution | No | Defaults to 1m. Use 1s only for short windows. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden and does it well: it warns that binary markets go one-sided near resolution (empty bid/ask is real market behavior, not missing data), that depth exists only where it was captured live, and that responses are large (a one-hour window at 1s yields 3,600 buckets per token across two tokens). No contradiction with annotations; it omits authentication, rate limits, and explicit side-effect statements, but otherwise is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into three crisp paragraphs — what it returns, a data-quality caveat, and an operational size warning — with the core purpose front-loaded. Every sentence pulls its weight; even the data-architecture note ('exists only where it was captured live') explains why the data can be sparse without adding redundancy. It is longer than one sentence but earned length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description conveys the essential shape of the data (price levels and resting sizes), its most surprising behavioral trait (one-sided resolution), and directly actionable guidance for choosing a window and resolution. The only real gap is that, with no output schema present, the description does not spell out the exact JSON/bucket structure of a snapshot; likewise pagination/phrasing is left to the schema's next_cursor reference, but for a read-only depth-history tool the coverage is otherwise impressively thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with defaults and examples for every parameter (e.g., one-hour window at 1s, resolution default 1m, cursor use), so the schema is already solid. 3100% schema description coverage means the description doesn't need to repeat parameter details; the description adds valuable cross-parameter trade-off reasoning: 1s only for short windows, and concrete bucket-count math for a given resolution/window. That raises it above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a completely new resource — 'Full L2 bid and ask ladders over time' with every price level and resting size — and pairs it with a specific verb, so an agent knows it retrieves historical depth snapshots, not current price. It does not explicitly route the agent away from sibling tools like get_price_history or get_market, so it falls slightly short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when the tool is the right choice ('This is data Polymarket does not archive: its /book endpoint returns only the current state') and hence when its output is needed beyond live data sources. It gives no explicit 'when not to use' or pointers to siblings (get_price_history, get_market), so tool-selection guidance is inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Price series per outcome token over time. Prices are probabilities in [0, 1].
Polymarket serves its own price history down to 1-minute buckets and that is free — use this tool when you need finer than a minute, or when you want prices aligned to the same timeline as order book depth. For 1-minute or coarser history alone, Polymarket's public API is equivalent.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Default 100, max 200 | |
| cursor | No | ||
| end_ts | Yes | ISO-8601 UTC, e.g. 2026-08-23T14:00:00Z | |
| start_ts | Yes | ISO-8601 UTC, e.g. 2026-08-23T14:00:00Z | |
| id_or_slug | Yes | Market slug | |
| resolution | No | Defaults to 1m |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full behavioral burden. It adds meaningful context: price is in [0,1] probability, the tool provides sub-minute precision, and the data is aligned to order book depth. It does not describe output pagination or exact return shape, but not a keiner gap for this read-only price data tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose. It is slightly verbose in the comparison sentence, but every clause adds value to the stories all relevant decision and semantic information. Might be trimmed slightly without losing content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description handles when-to-use and data semantics well, but there is no output schema and no description of return-format details such as the list structure of per-outcome price points, cursor pagination behavior, or limit implications. Input parameters are well covered in the schema, so not critical, but the absent output narrative leaves some room for ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, so by baseline it is a 3. The description adds no direct parameter-specific details beyond implying fine-grained resolution; the input schema already covers parameter defaults, limits, ISO timestamps, and resolution enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the resource (outcome token price series over time) and core semantic (prices are probabilities). It distinguishes the tool from Polymarket's public API and implicitly from siblings by focusing on finer-than-minute history and alignment with vibrancy and order-book timeline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly identifies when to use this tool: finer than one-minute buckets, or timelines aligned to order book depth. It also says not to use it for 1-minute or coarser history alone, directing to the Polymarket public API as an equivalent alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current plan, rate limits, history window and requests used. Call this when a request fails with a limit error, or before planning a large extraction, to see what the key is allowed to do.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly discloses the tool is a read-only usage/limits check that reports plan level, rate limits, history window, and request consumption. This is sufficient for a zero-parameter introspection tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core return values and then immediate usage context. No filler or repetition exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter usage/learning tool with no output schema, the description fully equips an agent to call it at the right time and know what it will receive. There are no gaps affecting selection or invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the description correctly avoids inventing parameter-related detail. The baseline of 4 applies because there is nothing for the description to add beyond confirming that calling it requires no inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as returning usage and quota information: current plan, rate limits, history window, and requests used. This is distinct from all sibling tools, which focus on market, series, event, and price data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit trigger conditions: call it when a request fails with a limit error, or before planning a large extraction. This tells the agent exactly when to invoke it, with no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
An event groups markets that resolve together — "what-price-will-solana-hit-august-17-23-2026" holds every price threshold for that week, and "btc-updown-5m-1787685000" is one 5-minute round. Use this to find the set of related markets to compare, then search_markets to get the markets themselves. Date filters are useful here: events carry an end_date.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Default 20 | |
| search | No | Substring matched against slug and title | |
| end_date_max | No | ISO-8601, events ending at or before this | |
| end_date_min | No | ISO-8601, events ending at or after this |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it does substantive work: it defines what an event is, illustrates both an event and a market identifier, and notes that events carry end_date. The only notable gap is explaining the response shape or pagination behavior, but for a read-only search tool the operational behavior is reasonably clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a few sentences long, includes concrete id examples, and connects the tool to the next step with search_markets. It is slightly front-loaded with background rather than the main purpose, but every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no required parameters, the description gives enough information for an agent to know why it might call this tool and how it relates to the surrounding workflow. A full response format is not described, but the event/market relationship and date semantics largely compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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. The description adds context around end_date and the event/market grouping, but it does not materially deepen the meaning of the individual search or limit parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description precisely defines the resource: an event is a grouping of markets that resolve together, and the tool's purpose is to find related market sets before using search_markets. It clearly separates this from the sibling tool search_markets by explaining the event/market relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit workflow: use this tool to find events, then use search_markets for the actual markets. It also points out that date filters are relevant because events carry an end_date. It does not name explicit exclusions or alternative tools like search_series, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find Polymarket markets by keyword. Start here — the other tools need a market slug, and slugs are not guessable. Coverage is Polymarket crypto markets: up/down contracts at 5m, 15m and 4h, price thresholds like "bitcoin-above-80k", and related event markets. Resolved markets are excluded unless include_closed is true, which is usually what you want for historical analysis. For a whole family of markets rather than one, search_series is more reliable than guessing slug patterns here.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Default 20 | |
| search | No | Substring matched against slug and question, e.g. "btc-updown" or "bitcoin-above" | |
| end_date_max | No | ISO-8601, markets ending at or before this | |
| end_date_min | No | ISO-8601, markets ending at or after this | |
| include_closed | No | Include markets that have already resolved. Set true for historical work. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so this description carries the behavioral-disclosure burden. It does that reasonably well by explaining that resolved markets are excluded by default, that include_closed flips that behavior, and that coverage is limited to Polymarket crypto markets. It stops short on return-shape/pagination expectations, but the important filtering defaults are clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The five sentences are information-dense without being padded: purpose, first-step rationale, scope, closed-market default, and sibling alternative each contribute distinct meaning. The introduction is a bit of run-on phrasing, but there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description supplies the essential context an agent needs to choose and use the tool, especially the entry-point position and the default exclusion of resolved markets. However, there is no output schema or explicit statement about what the result shape contains, ordering, or whether pagination matters, so the agent has to infer something important about how to consume the results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all five parameters with useful descriptions, including call behavior. The tool description mainly paraphrases that behavior (include_closed/historical analysis) rather than adding new semantics. Since schema coverage is 100%, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb and resource: 'Find Polymarket markets by keyword.' It clarifies coverage (crypto up/down and threshold contracts) and differentiates itself from slug-dependent sibling tools by explicitly warning that slugs are not guessable and that search_series is better for a family of markets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says to 'start here' and explains why: other tools need a market slug, and this tool is the way to obtain it. It also names search_series as an alternative for whole market families and explains that historical work should pass include_closed everything.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A series is a recurring family of markets — "btc-up-or-down-5m" is every BTC 5-minute up/down contract ever created. Use this when the question is about a kind of market rather than a specific one: it is more reliable than guessing at slug patterns with search_markets. Take the series slug, then use search_events to find its individual rounds.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Default 20 | |
| search | No | Substring, e.g. "btc-up-or-down" or "solana" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers some behavior: it clarifies that series names like 'btc-up-or-down-5m' represent many recurring contracts and that the tool is more reliable than search_markets. However, it does not mention pagination, default/limit behavior, or any response details. It is a middle ground.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: concept with example, when-to-use, and next-step instruction. It is compact, front-loaded, and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No schema exists; the description provides a clear workflow and example, making it complete enough to call. It could add details about default limit or filtering, but the description plus schema is strong and the extra context would be marginal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully covers both parameters (100% coverage), so the baseline is 3. The description adds context about using the slug as search input but does not add meaning beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description defines what a series is, gives a concrete example, and clearly distinguishes the tool from sibling tools like search_markets and search_events. The behavior is specific: searching recurring series rather than individual markets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance says this tool is for 'a kind of market rather than a specific one,' warns against guessing slug patterns with search_markets, and instructs the next step to use search_events on the resulting slug. This is clear routing with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.2.3get_market_metrics2 fields changedInput schema / properties / limit / descriptionPrevious value: -"Default 100"New value: +"Default 100, max 200"Input schema / properties / limit / maximumPrevious value: -500New value: +200get_price_history2 fields changedInput schema / properties / limit / descriptionPrevious value: -"Default 100"New value: +"Default 100, max 200"Input schema / properties / limit / maximumPrevious value: -500New value: +200v0.1.0get_marketget_market_metricsget_order_book_historyget_price_historyget_usagesearch_eventssearch_marketssearch_seriesThe three search_* tools target distinct entities (individual markets, recurring series, and event groupings), and the descriptions clarify which search to start with, but an agent could still hesitate between search_series and search_events for some workflows. The get_* tools are clearly separated by data type: order book depth, price series, and derived metrics.
All tool names follow a consistent verb_noun pattern: search_* for discovery and get_* for retrieval. There is no mixed casing, vague verb, or off-pattern name.
With eight tools, the server is well-scoped: discovery tools for each Polymarket entity, one market detail tool, three historical data tools, and one usage-account tool. Each tool fills a distinct role.
The read-only analytics workflow is well covered: find a market, expand to series or events, inspect a market, and then retrieve price, orderbook, or quality time series. A minor gap is the lack of an explicit current-orderbook snapshot endpoint, though historical snapshots and market detail cover most needs.
Order-book depth & history for Polymarket, Kalshi & Limitless. Keyless demo, key for full access.
Live Kalshi + Polymarket prediction-market data and cross-venue arbitrage spreads, one schema.
Polymarket MCP — prediction-market data via Gamma + CLOB public APIs.
Live prediction markets: Polymarket + Kalshi prices, odds, order books. Pay-per-call USDC, no key.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/polyorderbooks/mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
