Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@orcatrace-mcp What's the latest market pulse?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for OrcaTrace — pay-per-call Polymarket intelligence for AI agents. Track smart money and see what others miss across 42K prediction markets: quality-gated repricings with order-book microstructure, tracked-whale entries annotated with each wallet's hold-to-resolution calibration (follow or fade), AI-detected predetermined-outcome markets, on-demand single-market research, and 4-hourly synthesized digests — one unified, index-polled feed.
Pay per call with USDC on Base via x402 — no account, no API key.
5 free tools — no wallet, no API key.
8 paid tools — flat per-call USD prices ($0.01–$1.00), settled in USDC on Base Mainnet via x402.
The whale track record is free and verifiable. get_track_record publishes the aggregate
hold-to-resolution win rate, follow/fade ROI, per-odds-band breakdown, and top wallets with
full public addresses — so you can cross-check every claim on Polymarket before you
pay. Preview every paid response shape free with get_sample.
{
"mcpServers": {
"orcatrace": {
"command": "npx",
"args": ["-y", "orcatrace-mcp"]
}
}
}You get get_index, get_pulse, get_digest_brief, get_sample, get_track_record.
Add an EVM wallet private key (0x-prefixed) that holds USDC on Base Mainnet:
{
"mcpServers": {
"orcatrace": {
"command": "npx",
"args": ["-y", "orcatrace-mcp"],
"env": { "PRIVATE_KEY": "0x..." }
}
}
}The paid tools then settle each call automatically.
Claude Code:
claude mcp add orcatrace -- npx -y orcatrace-mcp
# with a wallet:
claude mcp add orcatrace --env PRIVATE_KEY=0x... -- npx -y orcatrace-mcpClaude Desktop / Cursor: add the JSON block above to your MCP config
(claude_desktop_config.json or .cursor/mcp.json).
Related MCP server: predmarket-mcp
Tool | Endpoint | Description |
|
| Current feed index — poll target to detect new items (~10min cadence). |
|
| Top-3 24h repricings (noise-filtered) + a digest teaser — the free hook. |
|
| Digest teaser: title + summary, no analysis (full digest is |
|
| Static samples of every paid response shape (signal, whales, digest). |
|
| Verifiable whale-calibration scorecard: win rate, follow/fade ROI, per-odds-band breakdown, top-10 wallets with full public addresses. |
Tool | Endpoint | Price (USD) | Description |
|
| $0.01 | Most recent feed item — mover, whale entry (with calibration), or predetermined signal. |
|
| $0.01 | One feed item: quality-gated mover (+microstructure), named whale entry, or predetermined signal. Optional |
|
| $0.03 | Batch of up to 20 feed items. Optional |
|
| $0.02 | Markets resolving within |
|
| $0.05 | Historical digests (up to 7 days, 4h cadence). Optional |
|
| $0.05 | Whale calibration table: per-wallet win rates by odds band, mirror/fade ROI, follow/fade labels (min 30 resolved entries). |
|
| $0.10 | Full Polymarket Intelligence Digest (every 4h): what repriced and why across 42K markets — synthesized analysis. |
|
| $1.00 | Single-market deep-dive: 7-day price action + order book + whale positioning + news, synthesized into a thesis. Requires |
Prices are flat per call — no bundles, no entitlements. Confirm live prices any time via
the free get_sample / the site.
OrcaTrace speaks the x402 exact scheme. The API's 402 advertises a
Base (USDC, EIP-3009) rail; this MCP settles on Base:
The MCP requests a paid endpoint. With no payment, the API replies HTTP 402 with the accepted terms.
If PRIVATE_KEY is set, the MCP settles the call via the standard @x402/fetch V2
client and retries. If no key is set, the MCP returns the 402 price terms so you can
see the cost without paying.
The API returns the data plus a payment block.
You are never charged for an error. The feed and digest routes are compute-first /
settle-after — the full answer is computed before you are charged, and the digest returns
503 (no charge) rather than serving stale. The proxied-compute routes (get_resolving,
get_whales, get_research) settle-early with a guaranteed refund — if the API charges
but cannot deliver, the payment is refunded.
No accounts, no API keys — just a wallet with USDC on Base Mainnet.
Variable | Required | Description |
| No | 0x-prefixed wallet key with USDC on Base Mainnet. Required to pay the 8 paid tools on a live API. Free tools work without it; without a key the paid tools surface the 402 price terms. |
| No | Override the API base URL (default |
OrcaTrace provides informational prediction-market data and analysis aggregated from public sources. Whale calibration measures entries held to resolution, not trader P&L. Nothing here is financial advice, and everything is provided as-is without warranty. See https://api.orcatrace.dev/terms.txt.
Docs for agents: https://api.orcatrace.dev/llms.txt · full: https://api.orcatrace.dev/llms-full.txt
MIT © jcislo
PAID $0.10 via x402. The full Polymarket Intelligence Digest (generated every 4h): what repriced and why across 42K markets — significant moves, whale positioning read through calibration, predetermined-outcome signals, and international news context. Synthesized analysis, not raw data. Never serves stale (returns 503, no charge, if generation falls behind). Free teaser: get_digest_brief. Pays USDC on Base via x402. Compute-first / settle-after — you are never charged for an error. Set PRIVATE_KEY (wallet with USDC on Base Mainnet) to pay on a live API; without a key the call returns the 402 price terms.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: paid ($0.10), compute-first/settle-after (never charged for errors), freshness policy (never serves stale, returns 503 if behind), and returns 402 without a key. This is exemplary transparency.
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?
Every sentence adds critical value: payment, content, analysis type, freshness, free alternative, payment mechanics, and key requirement. It is dense but well-structured, front-loading the payment requirement and delivering comprehensive information without 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?
Given no output schema, the description thoroughly covers the operational aspects: what the digest contains, when it's generated, how payment works, error statuses (503, 402), and the free alternative. It is complete and leaves no critical gaps.
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?
There are no parameters in the schema (0 params), so the baseline per rubric is 4. The description appropriately adds context about the PRIVATE_KEY environment variable, which is not a parameter but is essential for usage, without cluttering parameter semantics.
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 it provides the full Polymarket Intelligence Digest, generated every 4 hours, and details what it contains (significant moves, whale positioning, news context). It distinguishes itself from the sibling get_digest_brief by describing the latter as a free teaser.
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 names get_digest_brief as a free alternative, and provides clear usage conditions: payment via x402, PRIVATE_KEY requirement, and the 402 price terms when no key is set. This tells the agent when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Polymarket Intelligence Digest teaser: title + summary, no analysis (GET /v1/digest/brief). The full digest is the paid get_digest tool ($0.10). FREE, rate-limited 5/min per IP, no wallet or API key required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it is free, rate-limited at 5/min per IP, requires no wallet/API key, and returns only a title/summary without analysis. Since no annotations exist, this description fully covers the safety/access profile.
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 concise sentences deliver purpose, endpoint, cost, rate limit, and auth requirements without waste. Front-loaded with main purpose.
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 tool with no output schema, the description provides sufficient context: what it returns, what it omits, access constraints, and alternative. Complete for its complexity.
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 input schema has zero parameters, so baseline score 4 applies; description adds no parameter details because none exist.
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 tool returns a teaser with title and summary, explicitly excludes analysis, and identifies the endpoint. Distinguishes from siblings by contrasting with the paid get_digest tool.
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 mentions the alternative get_digest for the full paid digest, and specifies costs, rate limit, and auth-free access, providing clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PAID $0.05 via x402. Historical Polymarket Intelligence Digests (up to 7 days, 4h cadence) — track how prediction-market narratives evolved. Example: hours=24, limit=6. Pays USDC on Base via x402. Compute-first / settle-after — you are never charged for an error. Set PRIVATE_KEY (wallet with USDC on Base Mainnet) to pay on a live API; without a key the call returns the 402 price terms.
| Name | Required | Description | Default |
|---|---|---|---|
| hours | No | Lookback window in hours (up to 168 / 7 days) | |
| limit | No | Number of digests to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the paid nature ($0.05 via x402), the compute-first/settle-after model, that errors are never charged, and the behavior without a PRIVATE_KEY (returns 402 price terms). This is comprehensive behavioral context.
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 dense but not overly long; it front-loads payment info before purpose. All content is relevant, but the structure could be improved by stating the primary function first. Still, no wasted sentences.
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 lacking an output schema, the description covers the tool's scope, cost, auth requirements, error handling, and example usage, making it fully sufficient for an agent to decide when and how to invoke it.
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 covers 100% of parameters with clear descriptions. The description adds a concrete usage example (hours=24, limit=6) that clarifies typical parameter values, though it doesn't add new semantic meaning 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?
Description clearly states the tool returns historical Polymarket Intelligence Digests with a 7-day lookback and 4-hour cadence, using a specific verb+resource. The 'historical' aspect differentiates it from sibling tools like get_digest and get_latest.
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 usage for tracking how prediction-market narratives evolved and provides an example (hours=24, limit=6), but does not explicitly state when to use this over siblings or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current Polymarket feed index — poll target to detect new items (cadence ~10min) before paying for a signal (GET /v1/index). FREE, rate-limited 5/min per IP, no wallet or API key required.
| 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 and does so excellently. It discloses that the tool is free, read-only (poll target), rate-limited to 5/min, and requires no authentication. It also adds cadence and endpoint details, which are valuable behavioral traits beyond any structured data.
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 highly concise, packing purpose, usage, cadence, endpoint, and access constraints into two efficient sentences. Every element adds value, and it is front-loaded with the core purpose before delivering operational details.
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 tool with no output schema, the description is complete. It covers what the tool returns, when to use it, how often to poll, the rate limit, and authentication requirements. No further context is needed for an agent to correctly select and invoke it.
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 zero parameters, so the baseline is 4. The description adds context about the HTTP endpoint (GET /v1/index) and the purpose, but no parameter explanations are needed. It does not repeat schema info beyond what is already empty.
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 this tool returns the current Polymarket feed index and identifies its specific role as a polling target to detect new items. It distinguishes itself from sibling tools like get_signal by framing the index as a preliminary check before paying for a signal.
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 states when to use: poll target to detect new items at ~10min cadence, before paying for a signal. It also provides operational constraints (FREE, rate-limited 5/min per IP, no auth) which inform usage decisions. This implies not for fetching the signal itself, giving clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PAID $0.01 via x402. Most recent Polymarket feed item — a quality-gated mover, a tracked-whale entry (with hold-to-resolution calibration), or an AI-detected predetermined-outcome signal. Same shape as get_signal without an index. Poll get_index (free) first; preview the shape with get_sample (free). Pays USDC on Base via x402. Compute-first / settle-after — you are never charged for an error. Set PRIVATE_KEY (wallet with USDC on Base Mainnet) to pay on a live API; without a key the call returns the 402 price terms.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the paid nature ($0.01 via x402), the payment mechanism (USDC on Base), and the compute-first/settle-after model where users are never charged for an error. It also reveals the response without a key (402 price terms), providing complete transparency about tool behavior.
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 information-dense and front-loaded with the cost, but it contains a minor redundancy: 'PAID $0.01 via x402' and 'Pays USDC on Base via x402' both state the x402 payment. Otherwise, every sentence provides unique value and the structure is logical.
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?
Given the tool's simplicity (no params, no output schema), the description covers everything an agent needs: purpose, cost, usage sequence, prerequisites, and how to discover the response shape via get_sample. It is fully self-contained with appropriate cross-references to sibling tools.
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 input schema has zero parameters, so a baseline score of 4 applies. The description adds no parameter-specific semantics because there are none to describe, and it appropriately focuses on behavioral and usage context instead.
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 that get_latest returns the most recent Polymarket feed item and enumerates the types of items (quality-gated mover, tracked-whale entry, AI-detected predetermined-outcome signal). It distinguishes itself from get_signal by saying 'Same shape as get_signal without an index', making the purpose specific and 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?
It gives explicit usage instructions: 'Poll get_index (free) first; preview the shape with get_sample (free)' and provides the prerequisite of setting PRIVATE_KEY for live API use, noting the behavior without a key. This clearly guides when and how to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Top-3 Polymarket repricings over 24h (noise-filtered) plus a digest teaser — the free hook (GET /v1/pulse). FREE, rate-limited 5/min per IP, no wallet or API key required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses key behavioral traits: 'noise-filtered', 'FREE', 'rate-limited 5/min per IP', and 'no wallet or API key required'. It doesn't describe return format or what the digest teaser entails, so not a 5.
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 sentences, front-loaded with the core function, then practical constraints. No wasted words; efficiently structured.
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?
Given no parameters, no output schema, and simple read-only nature, the description is complete: it explains what is returned, the endpoint, rate limit, and auth requirements. An agent can invoke it correctly based on this.
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?
Input schema has zero parameters, so baseline is 4. The description mentions 'no wallet or API key required' which clarifies auth is not a parameter, and there are no parameter semantics to explain beyond that.
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 tool returns 'Top-3 Polymarket repricings over 24h (noise-filtered) plus a digest teaser', which is a specific resource and scope. It distinguishes itself from siblings like get_index and get_digest_brief by focusing on repricings and the free hook.
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?
It provides clear practical context: 'FREE, rate-limited 5/min per IP, no wallet or API key required' implies usage for unauthenticated users needing a free sample. However, it does not explicitly name alternative tools or state when not to use it, so it's short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PAID $1.00 via x402. Single-market deep-dive: 7-day price action + live order book + tracked-whale positioning with calibration + related international news, synthesized into a thesis with risks and an actionable bottom line. Generated on demand (10-60s; cached 30 min). Pass the market slug from polymarket.com/market/ or from a feed item. Pays USDC on Base via x402. Settle-early with a guaranteed refund — if the API charges but cannot deliver, the payment is refunded. Set PRIVATE_KEY (wallet with USDC on Base Mainnet) to pay on a live API; without a key the call returns the 402 price terms.
| Name | Required | Description | Default |
|---|---|---|---|
| market | Yes | Polymarket market slug, e.g. from polymarket.com/market/<slug> or a feed item |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses payment via x402, cost, generation time, caching, USDC on Base, refund policy, and the need for PRIVATE_KEY, including behavior without a key (returns 402 price terms). This is comprehensive behavioral disclosure.
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 longer but every sentence conveys relevant information: cost, output, timing, input, payment mechanics, refund, and key requirement. There is minor redundancy between 'PAID $1.00 via x402' and 'Pays USDC on Base via x402', but overall it is well-structured.
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 standalone tool with no output schema, the description covers input, output content, timing, caching, payment, refund, and failure mode. It is complete enough for an agent to decide and invoke correctly.
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 has one parameter, market, with a description matching the text. The description repeats the slug instruction but adds no new semantic detail beyond the schema, so baseline 3 applies.
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 tool performs a single-market deep-dive, synthesizing price action, order book, whale positioning, and news into a thesis with risks and a bottom line. This is a specific verb+resource and distinguishes from sibling tools like get_index or get_digest which likely provide broader market views.
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 indicates the use case: a paid, on-demand deep-dive for a specific market, with instructions to pass the market slug from a URL or feed item. It does not explicitly compare to alternatives, but the single-market scope and payment prerequisites provide clear context for when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PAID $0.02 via x402. Polymarket markets resolving within withinHours (1-72): odds, contested-vs-converged, liquidity, and order-book microstructure for the nearest expiries. Mechanical short-interval markets are excluded by default (set includeNoise=true to include them). Pays USDC on Base via x402. Settle-early with a guaranteed refund — if the API charges but cannot deliver, the payment is refunded. Set PRIVATE_KEY (wallet with USDC on Base Mainnet) to pay on a live API; without a key the call returns the 402 price terms.
| Name | Required | Description | Default |
|---|---|---|---|
| withinHours | No | Only markets resolving within this many hours (1-72) | |
| includeNoise | No | Include mechanical short-interval markets (default false) | |
| minLiquidity | No | Minimum market liquidity filter |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It fully discloses payment cost ($0.02), payment mechanism (x402), refund guarantee, private key requirement, and behavior without a key (returns 402 terms). This is exceptional transparency about the tool's operational behavior and prerequisites.
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 information-dense but well-structured: it opens with the core purpose and data returned, then covers filtering, payment, and auth in separate sentences. Each sentence adds value, but the density may require careful reading; still appropriately sized for the tool's complexity.
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 tool has no output schema or annotations, yet the description covers what data is returned, parameter behavior, payment/refund policies, and authentication requirements. It is complete enough for an agent to understand the tool's full context, including failure modes (402 without key) and live vs. price-term behavior.
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 coverage is 100%, so parameters are documented structurally. The description adds meaningful context beyond the schema by explaining 'withinHours' range (1-72), the default for 'includeNoise', and the meaning of 'mechanical short-interval markets'. This enriches the schema's basic descriptions, though 'minLiquidity' is only covered by 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 tool retrieves Polymarket markets resolving within a specified time window, with specific data fields (odds, contested-vs-converged, liquidity, order-book microstructure). This specific verb+resource+scope distinguishes it from sibling tools like get_pulse or get_digest, which likely serve different purposes.
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 clear conditions: mechanical short-interval markets excluded by default, includeNoise=true to include them, and live API requires PRIVATE_KEY with USDC on Base, otherwise returns 402 price terms. It does not explicitly name alternatives but gives enough contextual usage guidance for an agent to decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Static samples of every paid Polymarket response shape (signal, whales, digest), explicitly labelled — use it to learn the contract before paying (GET /v1/sample). FREE, rate-limited 5/min per IP, no wallet or API key required.
| 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 fully discloses key behaviors: it is FREE, rate-limited to 5/min per IP, requires no wallet or API key, and returns static labelled samples rather than live data. This goes beyond typical descriptions.
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?
A single, information-dense sentence covers purpose, usage, cost, rate limit, auth, and static nature. Every element earns its place without waste.
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 tool with no output schema, the description is complete: it explains what the sample is, why someone would use it, and all constraints. No gaps remain.
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 zero parameters, so the baseline is 4. The description adds no parameter details but also doesn't need to; the empty schema is self-explanatory.
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 tool provides 'Static samples of every paid Polymarket response shape' and lists specific shapes (signal, whales, digest). This distinguishes it from sibling tools that return actual data or other types of information.
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 explicitly says to 'use it to learn the contract before paying', giving clear when-to-use guidance. It also differentiates from paid alternatives by being FREE and sample-only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PAID $0.01 via x402. One Polymarket feed item: a quality-gated mover (volume >= $10k & depth >= $2.5k, with order-book microstructure), a named whale entry (with calibration + microstructure), or a predetermined signal. Pass index=N for a specific item; omit for the latest. Pays USDC on Base via x402. Compute-first / settle-after — you are never charged for an error. Set PRIVATE_KEY (wallet with USDC on Base Mainnet) to pay on a live API; without a key the call returns the 402 price terms.
| Name | Required | Description | Default |
|---|---|---|---|
| index | No | Feed index N for a specific item (from get_index); omit for the latest |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the paid nature ($0.01 via x402), the compute-first/settle-after model (no charge on error), the three possible return types, and the behavior without a key (returns 402 price terms). This goes well beyond minimal requirements.
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 packs essential operational details (cost, types, index, payment, error safety) into a compact set of sentences. It's slightly dense but each sentence contributes value; minor structural improvements could separate payment setup from return types.
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 covers the tool's purpose, parameters, payment prerequisites, and behavioral guarantees (free on error). It lacks explicit response format, but given the absence of an output schema, it could be more explicit about return values; still, it provides enough context for an agent to decide.
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 documents the single parameter index with its description, including 'omit for the latest.' The description repeats this and adds 'Pass index=N for a specific item,' but no new semantic meaning beyond the schema. Coverage is 100%, so baseline is 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 clearly identifies the tool's function: retrieving a single Polymarket feed item (mover, whale entry, or predetermined signal). It distinguishes from siblings by supporting an optional index parameter and indicating it returns one item, unlike get_signals (plural). The verb 'get' plus specific resource is clear.
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 explains exactly how to use the tool: pass index for a specific item or omit for the latest, and notes the need for PRIVATE_KEY for live payment. It references get_index for obtaining the index, providing contextual linkage. However, it doesn't explicitly contrast when to use get_signal vs get_signals or other siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PAID $0.03 via x402. Batch of up to 20 Polymarket feed items: quality-gated movers with order-book microstructure, whale entries with calibration, and predetermined signals. Poll get_index (free), then pass since=N for new items; filter with type. Pays USDC on Base via x402. Compute-first / settle-after — you are never charged for an error. Set PRIVATE_KEY (wallet with USDC on Base Mainnet) to pay on a live API; without a key the call returns the 402 price terms.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Filter by item type: mover, whale_entry, or predetermined | |
| count | No | Max items to return (up to 20) | |
| since | No | Return items after this feed index (from get_index) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden. It discloses the exact cost ($0.03 via x402), the batch limit, the requirement for PRIVATE_KEY, the 402 response without a key, and the guarantee that users are never charged for an error.
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?
Every sentence serves a purpose: cost, contents, usage workflow, payment mechanics, and key requirements. The description is front-loaded with the most critical operational detail (paid nature) and contains no filler.
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 paid feed tool with 3 optional params and no output schema, the description covers all necessary usage context: authentication (PRIVATE_KEY), pricing, error safety, pagination (since), filtering (type), and the integration with get_index. An agent has enough information to invoke correctly.
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 describes all three parameters at 100% coverage, so the baseline is 3. The description adds value by explaining the relationship between since and get_index, and by confirming count's maximum of 20. It does not go into deeper detail for each enum value, but the schema already covers that.
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 this as a paid batch endpoint for Polymarket feed items, explicitly listing the three item types (mover, whale_entry, predetermined). It distinguishes itself from free siblings like get_index by noting the paid nature and the requirement to poll get_index first.
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?
Provides an explicit workflow: 'Poll get_index (free), then pass since=N for new items; filter with type.' It also clarifies when payment is required, how to obtain price terms without a key, and the compute-first/settle-after behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verifiable whale-calibration scorecard — the free proof behind the paid get_whales tool: aggregate hold-to-resolution win rate, follow/fade ROI, per-odds-band breakdown, and top-10 wallets with FULL public addresses so you can cross-check every claim on Polymarket (GET /v1/track-record). Measures entries held to resolution, not trader P&L — not financial advice. FREE, rate-limited 5/min per IP, no auth required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the transparency burden. It discloses rate limiting, no auth, free status, and the key measurement limitation (hold-to-resolution vs. P&L). It also highlights verifiability through full public addresses, which is useful behavioral context.
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 dense but contains no wasted words: it covers purpose, metrics, endpoint, scope caveat, and access limits in a compact form. The first sentence is a bit long, but it front-loads the core identity effectively.
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 having no output schema, the description enumerates the key output components (win rate, ROI, odds-band breakdown, top-10 wallets) and operational details (rate limit, auth, endpoint). It is thorough for a parameterless read-only tool with no output schema.
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 has zero parameters, so the description need not explain inputs. It doesn't add parameter details because there are none, and the baseline for 0-param tools is 4. The description correctly implies a parameterless GET call.
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 a specific deliverable ('Verifiable whale-calibration scorecard') and lists concrete metrics (win rate, ROI, odds-band breakdown, top-10 wallets). It distinguishes itself from the paid get_whales tool by positioning as the free proof, so it stands apart from siblings.
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 to use it: as a free verification companion to get_whales. It also clarifies scope (entries held to resolution, not P&L) and access constraints (free, 5/min rate limit, no auth). However, it does not explicitly list exclusions or alternative tools for different needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PAID $0.05 via x402. Whale calibration table: per-wallet hold-to-resolution win rates by odds band, mirror/fade ROI, and follow/fade labels (minimum 30 resolved entries). This is the data behind the whale_entry annotations in the signal feed; the free proof is get_track_record. Pays USDC on Base via x402. Settle-early with a guaranteed refund — if the API charges but cannot deliver, the payment is refunded. Set PRIVATE_KEY (wallet with USDC on Base Mainnet) to pay on a live API; without a key the call returns the 402 price terms.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses the payment mechanism ($0.05 via x402), refund policy, requirement for PRIVATE_KEY with USDC on Base, and behavior without a key (returns 402 price terms). No annotations are provided, so the description carries the full burden and does so thoroughly.
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 longer than typical but every sentence adds critical information: pricing, data content, relationship to sibling tools, refund guarantee, and key requirement. It is well-structured and front-loaded with the most important detail (paid).
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?
Given the complexity of a paid API with no output schema, the description covers all necessary aspects: what data is returned, how to pay, what happens if payment is charged but not delivered, and prerequisites. It even lists the specific metrics included in the table.
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 input schema has zero parameters, so baseline is 4. The description compensates by explaining the payment configuration (PRIVATE_KEY environment variable) which is not a schema parameter but is essential for invocation.
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 tool's function: it returns a whale calibration table with per-wallet hold-to-resolution win rates, mirror/fade ROI, and follow/fade labels. It also differentiates itself from the free alternative get_track_record by noting it's the paid data behind whale_entry annotations.
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 explicitly names get_track_record as the free proof alternative, implying when to use that instead. It also provides clear context for when to use this tool (when paying for the calibration table) and operational prerequisites (set PRIVATE_KEY).
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.
v1.0.0get_digestget_digest_briefget_digest_historyget_indexget_latestget_pulseget_researchget_resolvingget_sampleget_signalget_signalsget_track_recordget_whalesScored across 13 tools
Most tools are clearly distinct (get_index, get_sample, get_research, etc.), but get_latest and get_signal overlap significantly since get_signal can omit the index to return the latest item. get_track_record and get_whales are related but their descriptions clearly separate free proof from paid data.
All tools follow a consistent get_<noun> pattern with snake_case throughout. Plurals and modifiers (get_signals, get_digest_history) fit the convention and are predictable.
13 tools is well-scoped for a Polymarket intelligence API, covering free hooks, paid signals, digests, whale tracking, and research without over-expanding. Each tool has a clear role in the workflow.
The tool surface covers the core intelligence workflow: polling for new items, retrieving individual/batch signals, digest summaries and history, whale calibration, resolving markets, and on-demand research. Minor gaps exist (e.g., no simple market quote tool), but the domain is well-covered.
Pay-per-call DeFi and macro intel for AI agents. x402 USDC tools via streamable HTTP /api/mcp.
Production-grade MCP gateway delivering 8 real-time AI tools with instant x402 micropayments settled in USDC on Base Mainnet or SPL-USDC on Solana. Features Basescan contract auditing, wallet analytics, headless browser scraping, and pre-scraped oracle data feeds.
Production-grade MCP gateway delivering 8 real-time AI tools with instant x402 micropayments settled in USDC on Base Mainnet or SPL-USDC on Solana. Features Basescan contract auditing, wallet analytics, headless browser scraping, and pre-scraped oracle data feeds.
x402 MCP for agents: crypto prices, funding, DeFi yields, Polymarket, Base RPC + MCP security.