Skip to main content
Glama

Finding prediction market top holders

prediction_market_top_holders
Read-onlyIdempotent

Largest current holders for a Polymarket market.

Key fields:

  • Positions are share balances, not USD notional.

  • Position Value USD is current marked value, not payout at resolution.

  • Side Held is the share side currently held.

Pitfalls:

  • The visible holder table is the source of truth for holder-side concentration — do not infer risk, max loss, or potential profit unless the tool output explicitly provides it.

  • Output summary is based only on shown rows, not the entire holder table.

  • Large visible positions or labels do not by themselves identify smart money unless Nansen smart-money-labelled data supports it.

Prerequisites: If marketId is unknown, call prediction_market_lookup first.

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": {
      "request": "<request>"
    },
    "name": "prediction_market_top_holders"
  }
}

Input Schema

NameRequiredDescriptionDefault
requestYesRequest for prediction market top holders.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • addedInput schema / properties / request / additionalProperties
      Added value: +false
    • removedInput schema / properties / request / anyOf
      Removed value: -[
      -  {
      -    "additionalProperties": true,
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "description": "Request for prediction market top holders.",
      -    "properties": {
      -      "marketId": {
      -        "description": "Numeric Polymarket market ID (e.g. '654412'). Obtain this from the prediction_market_screener tool.",
      -        "maxLength": 100,
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "orderBy": {
      -        "anyOf": [
      -          {
      -            "enum": [
      -              "position_size",
      -              "unrealized_pnl_usd",
      -              "avg_entry_price"
      -            ],
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ],
      -        "default": null,
      -        "description": "Sort field. Pass an exact value above or None for default ('position_size')."
      -      },
      -      "orderByDirection": {
      -        "default": "DESC",
      -        "description": "Sort direction: 'ASC' or 'DESC' (case-insensitive).",
      -        "enum": [
      -          "ASC",
      -          "DESC",
      -          "asc",
      -          "desc"
      -        ],
      -        "type": "string"
      -      },
      -      "page": {
      -        "default": 1,
      -        "description": "Page number for paginated results.",
      -        "minimum": 1,
      -        "type": "integer"
      -      }
      -    },
      -    "required": [
      -      "marketId"
      -    ],
      -    "type": "object"
      -  }
      -]
    • addedInput schema / properties / request / description
      Added value: +"Request for prediction market top holders."
    • addedInput schema / properties / request / properties
      Added value: +{
      +  "marketId": {
      +    "description": "Numeric Polymarket market ID (e.g. '654412'). Obtain this from the prediction_market_screener tool.",
      +    "maxLength": 100,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "orderBy": {
      +    "anyOf": [
      +      {
      +        "enum": [
      +          "position_size",
      +          "unrealized_pnl_usd",
      +          "avg_entry_price"
      +        ],
      +        "type": "string"
      +      },
      +      {
      +        "type": "null"
      +      }
      +    ],
      +    "default": null,
      +    "description": "Sort field. Pass an exact value above or None for default ('position_size')."
      +  },
      +  "orderByDirection": {
      +    "default": "DESC",
      +    "description": "Sort direction: 'ASC' or 'DESC' (case-insensitive).",
      +    "enum": [
      +      "ASC",
      +      "DESC",
      +      "asc",
      +      "desc"
      +    ],
      +    "type": "string"
      +  },
      +  "page": {
      +    "default": 1,
      +    "description": "Page number for paginated results.",
      +    "minimum": 1,
      +    "type": "integer"
      +  }
      +}
    • addedInput schema / properties / request / required
      Added value: +[
      +  "marketId"
      +]
    • addedInput schema / properties / request / type
      Added value: +"object"
  2. Changed1 schema field changed
    • changedInput schema / properties / request / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": true,
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "description": "Request for prediction market top holders.",
      -    "properties": {
      -      "marketId": {
      -        "description": "Numeric Polymarket market ID (e.g. '654412'). Obtain this from the prediction_market_screener tool.",
      -        "maxLength": 100,
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "orderBy": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ],
      -        "default": null,
      -        "description": "Optional sort field. Common fields: positionSize, unrealizedPnlUsd, avgEntryPrice."
      -      },
      -      "orderByDirection": {
      -        "default": "desc",
      -        "description": "Sort direction when orderBy is provided.",
      -        "enum": [
      -          "asc",
      -          "desc",
      -          "ASC",
      -          "DESC"
      -        ],
      -        "type": "string"
      -      },
      -      "page": {
      -        "default": 1,
      -        "description": "Page number for paginated results.",
      -        "minimum": 1,
      -        "type": "integer"
      -      }
      -    },
      -    "required": [
      -      "marketId"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": true,
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "description": "Request for prediction market top holders.",
      +    "properties": {
      +      "marketId": {
      +        "description": "Numeric Polymarket market ID (e.g. '654412'). Obtain this from the prediction_market_screener tool.",
      +        "maxLength": 100,
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "orderBy": {
      +        "anyOf": [
      +          {
      +            "enum": [
      +              "position_size",
      +              "unrealized_pnl_usd",
      +              "avg_entry_price"
      +            ],
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "Sort field. Pass an exact value above or None for default ('position_size')."
      +      },
      +      "orderByDirection": {
      +        "default": "DESC",
      +        "description": "Sort direction: 'ASC' or 'DESC' (case-insensitive).",
      +        "enum": [
      +          "ASC",
      +          "DESC",
      +          "asc",
      +          "desc"
      +        ],
      +        "type": "string"
      +      },
      +      "page": {
      +        "default": 1,
      +        "description": "Page number for paginated results.",
      +        "minimum": 1,
      +        "type": "integer"
      +      }
      +    },
      +    "required": [
      +      "marketId"
      +    ],
      +    "type": "object"
      +  }
      +]
  3. Changed3 schema fields changed
    • removedInput schema / $defs
      Removed value: -{
      -  "PredictionMarketTopHoldersRequest": {
      -    "description": "Request for prediction market top holders.",
      -    "properties": {
      -      "marketId": {
      -        "description": "Numeric Polymarket market ID (e.g. '654412'). Obtain this from the prediction_market_screener tool.",
      -        "maxLength": 100,
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "orderBy": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ],
      -        "default": null,
      -        "description": "Optional sort field. Common fields: positionSize, unrealizedPnlUsd, avgEntryPrice."
      -      },
      -      "orderByDirection": {
      -        "default": "desc",
      -        "description": "Sort direction when orderBy is provided.",
      -        "enum": [
      -          "asc",
      -          "desc",
      -          "ASC",
      -          "DESC"
      -        ],
      -        "type": "string"
      -      },
      -      "page": {
      -        "default": 1,
      -        "description": "Page number for paginated results.",
      -        "minimum": 1,
      -        "type": "integer"
      -      }
      -    },
      -    "required": [
      -      "marketId"
      -    ],
      -    "type": "object"
      -  }
      -}
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / request / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": true,
      -    "type": "object"
      -  },
      -  {
      -    "$ref": "#/$defs/PredictionMarketTopHoldersRequest"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": true,
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "description": "Request for prediction market top holders.",
      +    "properties": {
      +      "marketId": {
      +        "description": "Numeric Polymarket market ID (e.g. '654412'). Obtain this from the prediction_market_screener tool.",
      +        "maxLength": 100,
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "orderBy": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "Optional sort field. Common fields: positionSize, unrealizedPnlUsd, avgEntryPrice."
      +      },
      +      "orderByDirection": {
      +        "default": "desc",
      +        "description": "Sort direction when orderBy is provided.",
      +        "enum": [
      +          "asc",
      +          "desc",
      +          "ASC",
      +          "DESC"
      +        ],
      +        "type": "string"
      +      },
      +      "page": {
      +        "default": 1,
      +        "description": "Page number for paginated results.",
      +        "minimum": 1,
      +        "type": "integer"
      +      }
      +    },
      +    "required": [
      +      "marketId"
      +    ],
      +    "type": "object"
      +  }
      +]
  4. Added

TDQS

A3.8/5.0
Behavior4/5

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

The annotations already cover safety (readOnly, idempotent, non-destructive), so the description does not need to repeat them. Instead, it adds genuinely useful caveats: positions are share balances rather than USD notional, position value is marked-to-market rather than the payout at resolution, and the output summary reflects only the visible rows in a paginated table. It does not mention rate limits or pagination mechanics, but the added cautions are substantive.

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

Conciseness4/5

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

The purpose comes first, followed by clearly labeled Key fields, Pitfalls, and Prerequisites sections. The formatting is easy to scan and no sentence is pure filler. A small amount of the field explanation overlaps with what the output schema likely already conveys.

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

Completeness5/5

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

An output schema exists, so the description need not explain return values, and it correctly focuses on interpretation caveats instead. The pagination and summary-scope warning and the concentration inference caveat cover the main failure modes for a holder-table tool. Nothing essential to calling and reading the result is missing.

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 the schema already documents page, orderBy, orderByDirection, and marketId in detail. The description adds only that marketId comes from a lookup tool, which is partly redundant with the schema and partly inconsistent with it. The baseline 3 is appropriate because the schema does the real work.

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

Purpose4/5

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

The first line states a specific verb and resource: largest current holders for a Polymarket market. That is unambiguous on its own. It stops short of a 5 because it never distinguishes itself from the sibling token_current_top_holders, leaving the agent to infer that this tool operates on markets rather than tokens.

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

Usage Guidelines3/5

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

The Prerequisites section gives one concrete routing rule: call prediction_market_lookup first if marketId is unknown. However, that conflicts with the input schema, which tells the caller to obtain marketId from prediction_market_screener, so the guidance is inconsistent. There is no guidance on when to prefer this tool over sibling holder-position tools such as prediction_market_position_detail.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources