mcp-server-polymarket

Overview Schema Source Related Servers Discussions Admin

Search markets, events and profiles

search

Read-onlyIdempotent

Find Polymarket events, markets, tags, and profiles by free-text topic query so you can retrieve matching predictions, then fetch details with get_event or get_market.

Instructions

Full-text search over Polymarket, the way the site's search box works. Start here when the user names a topic; then use get_event or get_market on a result.

Tool call template

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

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

Input Schema

Name	Required	Description	Default
`page`	No	Results page, from 1.
`limit`	No	Results per type.
`query`	Yes	Free text, e.g. 'fed rate cut'.
`status`	No	Event status to match.	open
`max_markets`	No	Markets to include per event.
`include_tags`	No	Also search tags.
`include_profiles`	No	Also search user profiles.

Output Schema

Name	Required	Description	Default
`tags`	No
`total`	No
`events`	No
`has_more`	No
`profiles`	No
`next_page`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 11, 2026

TDQS

A3.8/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral framing (relevance-based full-text matching, drill-down workflow) but omits how results are shaped or capped across the market/event/profile types or that status defaults to open.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the primary entry-point rule front-loaded and the follow-up action second. There is no boilerplate or redundant restatement of parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema and full annotation coverage mean return values and safety need not be described. For a seven-parameter hub tool the description supplies the key routing logic, though it omits that profile and tag results only appear when their flags are enabled.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every one of the seven parameters is already explained in the schema, including defaults and bounds. The description only reinforces that 'query' is free text and adds nothing about paging, status filtering, or the include_tags/include_profiles toggles, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Full-text search over Polymarket') and adds a concrete mental model ('the way the site's search box works'). It names follow-up siblings get_event and get_market, though the description itself does not enumerate the result types (markets, events, profiles) that the title lists.

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

Usage Guidelines4/5

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

Gives explicit entry-point guidance: 'Start here when the user names a topic,' plus a next-step handoff to get_event or get_market on a result. It does not state exclusions, such as when to skip search because the user already has a slug or ID, so the when-not side is missing.

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

Deploy Server