Историческая глубина стакана Polymarket для Claude, Cursor и любого другого MCP‑клиента — полные уровнировки L2 покупок и продажи с шагом в 1 секунду и с указанием разрешившихся исходов.
Related MCP server: polymarket-mcp-server
Ничего устанавливать не нужно: добавьте сервер в конфигурацию MCP‑клиента — он запустится через 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, та же структура.
Получите бесплатный ключ на polyorderbooks.com/signup. Бесплатный тариф обслуживает запросы с шагом в 1 секунду, как и платные планы, но за более короткий период истории.
Инструмент | Назначение |
| Повторяющиеся семейства — |
| Группы рынков, которые разрешаются вместе. |
| Отдельные рынки по ключевому слову или диапазону дат. |
| Полная информация об одном рынке, включая токены исходов и победителя. |
| Стаканы L2 во времени. То, что Polymarket не архивирует. |
| Серия цен по каждому токену исхода. |
| Спред, ликвидность и объём как временной ряд. |
| Тариф, лимиты запросов и квота. |
Каталог устроен так: серии → события → рынки. Запрашивайте вид рынка через search_series, группу, разрешающуюся вместе, через search_events, а конкретный рынок — через search_markets.
Стаканы становятся односторонними по мере разрешения рынков. В последнюю минуту 5‑минутного рынка 76 % снимков имеют пустую сторону покупки или продажи — никто не предлагает проигрышный исход. Это реальное поведение рынка, а не пропущенные данные, и оно разрушает анализ, предполагающий двусторонний стакан.
Длительность контракта меняет всё. У 4‑часового контракта стакан односторонний в 0,5 % времени, а у 5‑минутного — в 17 %. Выводы, сделанные по одному типу, не переносятся на другой.
Ответы разрастаются быстро. Час с шагом в 1 секунду — это 3 600 интервалов на токен, а у рынка два токена. Сужайте окно или берите более крупный шаг, а для продолжения пользуйтесь возвращаемым next_cursor.
Найдите BTC‑рынки с 5‑минутными контрактами, которые разрешились вчера, и покажите, как менялась глубина стакана в последние две минуты до соглашения.
Для этого рынка: сколько бы кончала покупка 100 акций по фактическому стакану за пять секунд до закрытия, по сравнению со средней ценой в тот момент?
Сравните спред и ликвидность по 5‑минутным, 15‑минутным и 4‑часовым BTC‑контрактам за последний день.
Второй запрос — и есть суть данных L2. Серия цен показывает, где был рынок; только стакан уровня описывает вам, по какой цене можно было продать.
Хороших аналогов существует несколько — kukapay/polymarket-predictions-mcp, demwick/polymarket-agent-mcp, PaulieB14/graph-polymarket-mcp. Они оборачивают собственные Gamma и CLOB API Polymarket и делают это аккуратно.
Они | Этот сервер | |
Живые котировки и текущий рынок | да | нет |
Заключение сделок | частично | нет |
Метаданные и разрешение | да | да |
История цен | 1 минута, от Polymarket | 1 секунда |
Историческая глубина стакана | недоступна | есть |
Различие структурное, а не просто вопрос усилий. Кнопка /book Polymarket отдаёт только текущее состояние, и ничто это состояние не архивирует, поэтому ни один сервер поверх этого API не сможет отдать вчерашние стаканы. Этот сервер обращается к архивной записи, снятой в реальном времени.
Если вы хотите торговать или получать живые котировки, используйте один из тех серверов — там это сделано лучше. Здесь стоит работать, когда речь идёт о том, как выглядел стакан в конкретный момент прошлого.
«POLYORDERBOOKS_API_KEY does not exist» — сервер сразу завершит работу, если ключ не задан. Пропишите его в блоке env конфигурации вашего MCP‑клиента, а не в окружении командной строки: MCP‑серверы не наследуют ваше окружение.
Ошибка аутентификации — ключи начинаются с pob_. Если вставляли из терминала, проверьте, что в конце нет скрытого символа перевода строки.
Усечённые или медленные ответы — час с шагом 1 секунда даёт 3 600 сегментов на токен, а у рынка их два. Сузьте окно, или используйте resolution: "1m", и продолжайте получать данные через next_cursor.
Пустые стаканы — это ожидаемо вблизи расчёта. Смотрите примечание выше про односторонний стакан.
897 192 снимка по 805 разрешившимся рынкам и трём длительностям контрактов публикуются под CC BY 4.0 с DOI, без регистрации:
doi.org/10.5281/zenodo.22084114
Это полезно, чтобы самостоятельно познакомиться в этих свойствах, прежде чем полагаться на API.
npm install
npm run build
POLYORDERBOOKS_API_KEY=pob_... npm run devСервер общается через stdio. Чтобы опробовать его без MCP‑клиента, передайте на stdin JSON‑RPC: сначала initialize, потом tools/list, затем tools/call.
polyorderbooks.com — API
docs.polyorderbooks.com — справка
Python client — установка pip install polyorderbooks
Бесплатный BTC‑пример — один рынок, без регистрации
MIT. Проект не связан с 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.
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_seriesScored across 8 tools
The 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.
Polymarket orderbook history, live books, trades and settlements, plus Hyperliquid perp books.
Order-book depth & history for Polymarket, Kalshi & Limitless. Keyless demo, key for full access.
Live Polymarket odds, order books, fee-inclusive quotes and non-custodial prediction trading.
Fetches live Polymarket prediction market orderbooks, implied Yes/No probabilities, volume, and wh
