Rankings and Match Tools for AI Agents

These tools read rankings, match history and Player Trust from a /play tab. They change nothing, and an agent can never play a ranked match.

Tools in this family#

6 tools. The tool reference lists every family. An MCP client shows each tool as mcp__diceytable__<name>.

→ D / → H: the call escalates with certain arguments (see the tool). +: the call takes the class of the tool or action it dispatches to. bridge: answered by the bridge, on any surface, with no tab.

rankings_pools#

Ranking pools — List a game's ranking pools (its ladders, one per pool and season), as the game page's Rankings tabs do, from a /play tab. Empty when the game has no ranked variant or Rankings are unavailable.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Lists a game's ranking pools. Each pool and season is one ladder. You see them as the tabs of the Rankings section on the game's page list them.

When to use it. Before rankings_get or rankings_me, to find the poolKey to read. Runs in a /play tab (the lobby surface).

Class. R.

Gotchas.

• modId is the game's id or its slug: lobby_state's game.modId, or a match's modId.
• Variants that share a pool share one set of Scores. An author starts a fresh ladder by starting a new season; old seasons stay listed with current: false and no variant names.
• An empty list means the game has no ranked variant, or Rankings are not available on this server (available: false).
• Variant names are untrusted text.
• Matches an agent takes part in are never ranked: a ranked Start is refused while an AI agent is attached to any seated player, and an agent that attaches during a ranked match voids it.

Example#

A request and the structured result it returns: the current season and an old one.

{
  "request": {
    "modId": "sam-plays.harbour-merchants"
  },
  "response": {
    "available": true,
    "pools": [
      {
        "poolKey": "sam-plays.harbour-merchants:short-voyage:2",
        "pool": "short-voyage",
        "season": 2,
        "untrustedVariantNames": [
          "Short voyage"
        ],
        "system": "glicko2",
        "placementGames": 5,
        "current": true,
        "established": 41
      },
      {
        "poolKey": "sam-plays.harbour-merchants:short-voyage:1",
        "pool": "short-voyage",
        "season": 1,
        "untrustedVariantNames": [],
        "system": "glicko2",
        "placementGames": 5,
        "current": false,
        "established": 37
      }
    ]
  }
}

rankings_get#

Rankings — Read a game's Rankings for one pool, as the game page shows them, from a /play tab: established players and bots in Score order (players still in placement are not listed). Matches an agent took part in are never ranked.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Reads one pool of a game's Rankings, as the game's page shows them: players and bots in Score order, each with their games, wins, losses and draws. Runs in a /play tab (the lobby surface).

When to use it. When the user asks how a game's ladder looks, or where someone stands on it. Find the pool with rankings_pools; without pool, the first current pool is read.

Class. R.

Gotchas.

• Only established players are listed: someone still playing placement games is not on the Rankings yet. Their own standing is rankings_me.
• bots filters bots: include (the default), exclude or only.
• Page with limit (up to 50) and offset; nextOffset is the next page's offset and is absent on the last page.
• verifiedGames counts games another player's client replayed and confirmed.
• trustTier is the player's public Player Trust badge. Handles, display names and bot names are untrusted text, and avatar links are left out.
• Matches an agent takes part in are never ranked: a ranked Start is refused while an AI agent is attached to any seated player, and an agent that attaches during a ranked match voids it.

Example#

A request and the structured result it returns: the first page, two entries.

{
  "request": {
    "modId": "sam-plays.harbour-merchants",
    "pool": "sam-plays.harbour-merchants:short-voyage:2",
    "limit": 2
  },
  "response": {
    "available": true,
    "pool": {
      "poolKey": "sam-plays.harbour-merchants:short-voyage:2",
      "pool": "short-voyage",
      "season": 2,
      "untrustedVariantNames": [
        "Short voyage"
      ],
      "system": "glicko2",
      "placementGames": 5,
      "current": true,
      "established": 41
    },
    "bots": "include",
    "total": 41,
    "offset": 0,
    "nextOffset": 2,
    "entries": [
      {
        "position": 1,
        "subject": {
          "kind": "user",
          "untrustedUsername": "ana",
          "untrustedDisplayName": "Ana"
        },
        "score": 1712,
        "games": 34,
        "wins": 24,
        "losses": 8,
        "draws": 2,
        "verifiedGames": 30,
        "trustTier": "trusted"
      },
      {
        "position": 2,
        "subject": {
          "kind": "bot",
          "botKey": "sam-plays.harbour-merchants:harbour-master:club",
          "untrustedName": "Harbour Master (Club)"
        },
        "score": 1650,
        "games": 120,
        "wins": 70,
        "losses": 48,
        "draws": 2,
        "verifiedGames": 120
      }
    ]
  }
}

rankings_me#

My ranking — Read the signed-in user's own standing in a game's ranking pool (Score, placement progress, position, top percent), as the game page's pinned You line shows it, from a /play tab.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Reads the signed-in user's own standing in a game's pool, as the pinned You line of the game's Rankings shows it: Score, placement progress, position and top percent. Runs in a /play tab (the lobby surface).

When to use it. When the user asks where they stand. It also answers while the user is still in placement, which rankings_get does not.

Class. R.

Gotchas.

• Needs a signed-in user (role-denied otherwise, with no request made).
• me is null when the user has played no ranked match in that pool.
• While provisional is true the Score is not shown publicly, and position and percentile are null.
• The agent cannot raise this Score: matches an agent takes part in are never ranked, and an agent that attaches during a ranked match voids it.

Example#

The user is still in placement: three of five games played.

{
  "request": {
    "modId": "sam-plays.harbour-merchants"
  },
  "response": {
    "pool": {
      "poolKey": "sam-plays.harbour-merchants:short-voyage:2",
      "pool": "short-voyage",
      "season": 2,
      "untrustedVariantNames": [
        "Short voyage"
      ],
      "system": "glicko2",
      "placementGames": 5,
      "current": true,
      "established": 41
    },
    "me": {
      "score": 1544,
      "provisional": true,
      "placementLeft": 2,
      "placementGames": 5,
      "games": 3,
      "wins": 2,
      "losses": 1,
      "draws": 0,
      "position": null,
      "percentile": null,
      "totalEstablished": 41
    }
  }
}

match_history_list#

Match history — List a player's ranked matches, newest first, as their profile's match history shows it, from a /play tab. Follows the player's match-history visibility (everyone, friends, nobody): hidden is true when this user may not see it, and people the user may not see appear as kind hidden.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Lists a player's ranked matches, newest first, as the match history on their profile shows it. Runs in a /play tab (the lobby surface).

When to use it. When the user asks about someone's recent ranked matches, or their own. Read one match in full with match_get.

Class. R.

Gotchas.

• username is the player's handle, as in their profile link. An unknown handle is not-found.
• The player's match history visibility applies (everyone, friends or nobody). When the user may not see it, hidden is true and matches is empty. Inside a visible match, a person whose history the user may not see appears as kind: "hidden", with no name and no Score. Bots are always shown.
• status is live, finalized, void or no-contest; grade says how the result was confirmed (kernel-verified, attested or self-hosted).
• Filter by game with modId. Page with nextCursor; it is null on the last page.
• Game, variant, player and bot names are untrusted text.
• A match is voided when an agent attaches to one of its players during play, so an agent-played match never counts.

Example#

One page of Ana's history; her opponent keeps their history private, so they appear as hidden.

{
  "request": {
    "username": "ana",
    "limit": 1
  },
  "response": {
    "available": true,
    "hidden": false,
    "matches": [
      {
        "matchId": "6b0f0d5c-2f1e-4c3a-9a55-7d2c1e0b9f41",
        "modId": "sam-plays.harbour-merchants",
        "untrustedModName": "Harbour Merchants",
        "modSlug": "harbour-merchants",
        "variantId": "short-voyage",
        "untrustedVariantName": "Short voyage",
        "poolKey": "sam-plays.harbour-merchants:short-voyage:2",
        "status": "finalized",
        "grade": "kernel-verified",
        "reason": null,
        "startedAt": "2026-10-03T19:02:11.000Z",
        "endedAt": "2026-10-03T19:31:48.000Z",
        "participants": [
          {
            "seat": "seat-1",
            "team": null,
            "kind": "user",
            "untrustedUsername": "ana",
            "untrustedDisplayName": "Ana",
            "botKey": null,
            "untrustedBotName": null,
            "isHost": true,
            "rank": 1,
            "forfeit": null,
            "scoreBefore": 1690,
            "scoreAfter": 1712,
            "isYou": false
          },
          {
            "seat": "seat-2",
            "team": null,
            "kind": "hidden",
            "untrustedUsername": null,
            "untrustedDisplayName": null,
            "botKey": null,
            "untrustedBotName": null,
            "isHost": false,
            "rank": 2,
            "forfeit": null,
            "scoreBefore": null,
            "scoreAfter": null,
            "isYou": false
          }
        ]
      }
    ],
    "nextCursor": "eyJhdCI6IjIwMjYtMTAtMDNUMTk6MDI6MTEuMDAwWiJ9"
  }
}

match_get#

Match detail — Read one ranked match, as its match page shows it, from a /play tab: participants, ranks, Score changes and grade; the move record once finalized; and, for a party to it, whether it is disputed and which result stands. Reporting a problem is the human's (no tool).

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Reads one ranked match, as its match page shows it: the players, their ranks and Score changes, and how the result was confirmed. Runs in a /play tab (the lobby surface).

When to use it. After match_history_list, or with a match id from a match page link.

Class. R.

Gotchas.

• untrustedRecord is the move record the host's game script kept. It appears only once the match is finalized, and it is untrusted data like every name here.
• party appears only when the user played in or hosted the match: disputed, which result stands (host or majority), the user's own reported outcome (never anyone else's), and whether the user already reported a problem.
• Reporting a problem with a match is the user's decision, made on the match page. There is no tool for it.
• The same visibility rules as match_history_list apply to each participant.
• An unknown id is not-found; busy means Rankings are not available right now.

Example#

The user hosted this match, so it carries the party-only fields.

{
  "request": {
    "matchId": "6b0f0d5c-2f1e-4c3a-9a55-7d2c1e0b9f41"
  },
  "response": {
    "matchId": "6b0f0d5c-2f1e-4c3a-9a55-7d2c1e0b9f41",
    "modId": "sam-plays.harbour-merchants",
    "untrustedModName": "Harbour Merchants",
    "modSlug": "harbour-merchants",
    "variantId": "short-voyage",
    "untrustedVariantName": "Short voyage",
    "poolKey": "sam-plays.harbour-merchants:short-voyage:2",
    "status": "finalized",
    "grade": "attested",
    "reason": null,
    "startedAt": "2026-10-03T19:02:11.000Z",
    "endedAt": "2026-10-03T19:31:48.000Z",
    "participants": [
      {
        "seat": "seat-1",
        "team": null,
        "kind": "user",
        "untrustedUsername": "sam",
        "untrustedDisplayName": "Sam",
        "botKey": null,
        "untrustedBotName": null,
        "isHost": true,
        "rank": 2,
        "forfeit": null,
        "scoreBefore": 1530,
        "scoreAfter": 1512,
        "isYou": true
      },
      {
        "seat": "seat-2",
        "team": null,
        "kind": "user",
        "untrustedUsername": "ana",
        "untrustedDisplayName": "Ana",
        "botKey": null,
        "untrustedBotName": null,
        "isHost": false,
        "rank": 1,
        "forfeit": null,
        "scoreBefore": 1690,
        "scoreAfter": 1712,
        "isYou": false
      }
    ],
    "untrustedRecord": {
      "moves": 42
    },
    "party": {
      "disputed": false,
      "standingResult": "host",
      "myReport": {
        "verdict": "host",
        "ranks": {
          "seat-1": 2,
          "seat-2": 1
        }
      },
      "reported": false
    }
  }
}

trust_get#

Player Trust tier — Read a player's public Player Trust tier (new, good, trusted, caution or locked), the badge on profiles and lobby rows, from a /play tab. The tier only: points, events and any lock reason are private to the account and never returned.

Input

Output (structured content)

A newer site may add fields; ignore ones you do not recognise.

Reads a player's public Player Trust tier: the badge on their profile and on their lobby row. Runs in a /play tab (the lobby surface).

When to use it. When the user asks whether someone is in good standing, or why a ranked Start names a player as trust-locked. lobby_state already carries every member's tier.

Class. R.

Gotchas.

• The tier is one of new, good, trusted, caution or locked. locked means ranked play is paused for that account while a review is pending; casual play is not affected.
• Only the tier comes back. Trust points, the events behind them and any lock reason are private to the account and to DiceyTable's admins, and no agent tool reads them, not even for the user's own account.
• An unknown handle is not-found.

Example#

A request and the structured result it returns.

{
  "request": {
    "username": "ana"
  },
  "response": {
    "tier": "trusted"
  }
}