PokerData

Find my hands

find_hands

Read-onlyIdempotent

Find hands the account has uploaded. Returns hand_id, session_id, handAt, position, cards, game, board, potType, street lines, and netBb. Solver grade buckets are not filled. If this account has no hands, offer the hosted upload page from get_upload_link (https://pokerdata.io/upload) instead of asking the user to paste histories into chat.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`sort`	Yes	Row order: newest first, largest win first, or largest loss first (the default).	biggest_loss
`limit`	Yes	Hands to return, 1 to 50.
`filter`	No	Hand-level filters, all optional.
`game_type`	No	Only hands of this game type. Matches hole-card count.
`session_id`	No	Only hands from this upload session (see list_my_sessions).
`table_size`	No	Only hands dealt at tables of this many seats.
`gto_vs_3bet_bucket`	No	Solver grade bucket for hero's action vs a 3-bet. Grades are not computed, so any value matches nothing rather than inventing a frequency.
`gto_plo5_rfi_bucket`	No	Solver grade bucket for PLO5 raise-first-in. Grades are not computed, so any value matches nothing.

Output Schema

TableJSON Schema

Name	Required	Description
`gto`	No	Always "not graded": solver grades are not attached.
`hint`	No	Where to upload hands when the account has none.
`hands`	No	Matching hands, sorted as requested.
`total`	No	Matching hands before the limit.
`gtoNote`	No	Why a solver-grade filter matches nothing.
`returned`	No	Hands in this response.

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedOct 16, 2026

changedInput schema / properties / filter / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "facedLimp": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "facedThreeBet": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "flopBetPctPot": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "max": {
-                "anyOf": [
-                  {
-                    "description": "Exclusive upper bound, % of pot.",
-                    "minimum": 0,
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "min": {
-                "anyOf": [
-                  {
-                    "description": "Inclusive lower bound, % of pot.",
-                    "minimum": 0,
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "flopFacedBetPctPot": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "max": {
-                "anyOf": [
-                  {
-                    "description": "Exclusive upper bound, % of pot.",
-                    "minimum": 0,
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "min": {
-                "anyOf": [
-                  {
-                    "description": "Inclusive lower bound, % of pot.",
-                    "minimum": 0,
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "flopFirstAction": {
-        "anyOf": [
-          {
-            "items": {
-              "enum": [
-                "check",
-                "bet",
-                "call",
-                "fold",
-                "raise"
-              ],
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "flopFirstResponseToBet": {
-        "anyOf": [
-          {
-            "items": {
-              "enum": [
-                "check",
-                "bet",
-                "call",
-                "fold",
-                "raise"
-              ],
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "foldedToThreeBet": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "isIpVsPfr": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "isPfr": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "limped": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "pfr": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "position": {
-        "anyOf": [
-          {
-            "items": {
-              "enum": [
-                "UTG",
-                "UTG1",
-                "UTG2",
-                "MP",
-                "LJ",
-                "HJ",
-                "CO",
-                "BTN",
-                "SB",
-                "BB"
-              ],
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "rfi": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "rfiOpp": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "riverBetPctPot": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "max": {
-                "anyOf": [
-                  {
-                    "description": "Exclusive upper bound, % of pot.",
-                    "minimum": 0,
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "min": {
-                "anyOf": [
-                  {
-                    "description": "Inclusive lower bound, % of pot.",
-                    "minimum": 0,
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "riverFacedBetPctPot": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "max": {
-                "anyOf": [
-                  {
-                    "description": "Exclusive upper bound, % of pot.",
-                    "minimum": 0,
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "min": {
-                "anyOf": [
-                  {
-                    "description": "Inclusive lower bound, % of pot.",
-                    "minimum": 0,
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "riverFirstAction": {
-        "anyOf": [
-          {
-            "items": {
-              "enum": [
-                "check",
-                "bet",
-                "call",
-                "fold",
-                "raise"
-              ],
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "riverFirstResponseToBet": {
-        "anyOf": [
-          {
-            "items": {
-              "enum": [
-                "check",
-                "bet",
-                "call",
-                "fold",
-                "raise"
-              ],
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "sawFlop": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "sawShowdown": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "threeBet": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "turnBetPctPot": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "max": {
-                "anyOf": [
-                  {
-                    "description": "Exclusive upper bound, % of pot.",
-                    "minimum": 0,
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "min": {
-                "anyOf": [
-                  {
-                    "description": "Inclusive lower bound, % of pot.",
-                    "minimum": 0,
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "turnFacedBetPctPot": {
-        "anyOf": [
-          {
-            "additionalProperties": false,
-            "properties": {
-              "max": {
-                "anyOf": [
-                  {
-                    "description": "Exclusive upper bound, % of pot.",
-                    "minimum": 0,
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              },
-              "min": {
-                "anyOf": [
-                  {
-                    "description": "Inclusive lower bound, % of pot.",
-                    "minimum": 0,
-                    "type": "number"
-                  },
-                  {
-                    "type": "null"
-                  }
-                ]
-              }
-            },
-            "type": "object"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "turnFirstAction": {
-        "anyOf": [
-          {
-            "items": {
-              "enum": [
-                "check",
-                "bet",
-                "call",
-                "fold",
-                "raise"
-              ],
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "turnFirstResponseToBet": {
-        "anyOf": [
-          {
-            "items": {
-              "enum": [
-                "check",
-                "bet",
-                "call",
-                "fold",
-                "raise"
-              ],
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "vpip": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "vsThreeBetAction": {
-        "anyOf": [
-          {
-            "description": "Opener's action vs a 3-bet: fold, call, or raise (4-bet).",
-            "items": {
-              "enum": [
-                "fold",
-                "call",
-                "raise"
-              ],
-              "type": "string"
-            },
-            "type": "array"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "wasSrp": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "wasThreeBetPot": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      },
-      "wonAtShowdown": {
-        "anyOf": [
-          {
-            "type": "boolean"
-          },
-          {
-            "type": "null"
-          }
-        ]
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "description": "Hand-level filters. Every field is optional; null means the filter is not applied.",
+    "properties": {
+      "facedLimp": {
+        "anyOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero acted after an opponent's open limp."
+      },
+      "facedThreeBet": {
+        "anyOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero's open was 3-bet."
+      },
+      "flopBetPctPot": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "max": {
+                "anyOf": [
+                  {
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Exclusive upper bound, % of pot."
+              },
+              "min": {
+                "anyOf": [
+                  {
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Inclusive lower bound, % of pot."
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Size of hero's flop bet, as % of pot."
+      },
+      "flopFacedBetPctPot": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "max": {
+                "anyOf": [
+                  {
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Exclusive upper bound, % of pot."
+              },
+              "min": {
+                "anyOf": [
+                  {
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Inclusive lower bound, % of pot."
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Size of the flop bet hero faced, as % of pot."
+      },
+      "flopFirstAction": {
+        "anyOf": [
+          {
+            "items": {
+              "enum": [
+                "check",
+                "bet",
+                "call",
+                "fold",
+                "raise"
+              ],
+              "type": "string"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero's first action on the flop."
+      },
+      "flopFirstResponseToBet": {
+        "anyOf": [
+          {
+            "items": {
+              "enum": [
+                "check",
+                "bet",
+                "call",
+                "fold",
+                "raise"
+              ],
+              "type": "string"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero's first action facing a flop bet."
+      },
+      "foldedToThreeBet": {
+        "anyOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero folded to a 3-bet."
+      },
+      "isIpVsPfr": {
+        "anyOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero was in position against the preflop raiser."
+      },
+      "isPfr": {
+        "anyOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero was the preflop raiser."
+      },
+      "limped": {
+        "anyOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero open-limped."
+      },
+      "pfr": {
+        "anyOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero raised preflop."
+      },
+      "position": {
+        "anyOf": [
+          {
+            "items": {
+              "enum": [
+                "UTG",
+                "UTG1",
+                "UTG2",
+                "MP",
+                "LJ",
+                "HJ",
+                "CO",
+                "BTN",
+                "SB",
+                "BB"
+              ],
+              "type": "string"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Keep hands where hero sat in one of these seats."
+      },
+      "rfi": {
+        "anyOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero raised first in."
+      },
+      "rfiOpp": {
+        "anyOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero had a raise-first-in opportunity (folded to hero)."
+      },
+      "riverBetPctPot": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "max": {
+                "anyOf": [
+                  {
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Exclusive upper bound, % of pot."
+              },
+              "min": {
+                "anyOf": [
+                  {
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Inclusive lower bound, % of pot."
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Size of hero's river bet, as % of pot."
+      },
+      "riverFacedBetPctPot": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "max": {
+                "anyOf": [
+                  {
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Exclusive upper bound, % of pot."
+              },
+              "min": {
+                "anyOf": [
+                  {
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Inclusive lower bound, % of pot."
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Size of the river bet hero faced, as % of pot."
+      },
+      "riverFirstAction": {
+        "anyOf": [
+          {
+            "items": {
+              "enum": [
+                "check",
+                "bet",
+                "call",
+                "fold",
+                "raise"
+              ],
+              "type": "string"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero's first action on the river."
+      },
+      "riverFirstResponseToBet": {
+        "anyOf": [
+          {
+            "items": {
+              "enum": [
+                "check",
+                "bet",
+                "call",
+                "fold",
+                "raise"
+              ],
+              "type": "string"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero's first action facing a river bet."
+      },
+      "sawFlop": {
+        "anyOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero saw a flop."
+      },
+      "sawShowdown": {
+        "anyOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hand reached showdown."
+      },
+      "threeBet": {
+        "anyOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero 3-bet."
+      },
+      "turnBetPctPot": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "max": {
+                "anyOf": [
+                  {
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Exclusive upper bound, % of pot."
+              },
+              "min": {
+                "anyOf": [
+                  {
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Inclusive lower bound, % of pot."
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Size of hero's turn bet, as % of pot."
+      },
+      "turnFacedBetPctPot": {
+        "anyOf": [
+          {
+            "additionalProperties": false,
+            "properties": {
+              "max": {
+                "anyOf": [
+                  {
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Exclusive upper bound, % of pot."
+              },
+              "min": {
+                "anyOf": [
+                  {
+                    "minimum": 0,
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Inclusive lower bound, % of pot."
+              }
+            },
+            "type": "object"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Size of the turn bet hero faced, as % of pot."
+      },
+      "turnFirstAction": {
+        "anyOf": [
+          {
+            "items": {
+              "enum": [
+                "check",
+                "bet",
+                "call",
+                "fold",
+                "raise"
+              ],
+              "type": "string"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero's first action on the turn."
+      },
+      "turnFirstResponseToBet": {
+        "anyOf": [
+          {
+            "items": {
+              "enum": [
+                "check",
+                "bet",
+                "call",
+                "fold",
+                "raise"
+              ],
+              "type": "string"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero's first action facing a turn bet."
+      },
+      "vpip": {
+        "anyOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero put money in voluntarily."
+      },
+      "vsThreeBetAction": {
+        "anyOf": [
+          {
+            "items": {
+              "enum": [
+                "fold",
+                "call",
+                "raise"
+              ],
+              "type": "string"
+            },
+            "type": "array"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Opener's action vs a 3-bet: fold, call, or raise (4-bet)."
+      },
+      "wasSrp": {
+        "anyOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hand was a single-raised pot."
+      },
+      "wasThreeBetPot": {
+        "anyOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hand was a 3-bet pot."
+      },
+      "wonAtShowdown": {
+        "anyOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "description": "Hero won at showdown."
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / filter / description
```
Added value: +"Hand-level filters, all optional."
```

addedInput schema / properties / game_type / description

Added value: +"Only hands of this game type. Matches hole-card count."

addedInput schema / properties / gto_plo5_rfi_bucket / description

Added value: +"Solver grade bucket for PLO5 raise-first-in. Grades are not computed, so any value matches nothing."

addedInput schema / properties / gto_vs_3bet_bucket / description

Added value: +"Solver grade bucket for hero's action vs a 3-bet. Grades are not computed, so any value matches nothing rather than inventing a frequency."

addedInput schema / properties / limit / description
```
Added value: +"Hands to return, 1 to 50."
```

addedInput schema / properties / session_id / description

Added value: +"Only hands from this upload session (see list_my_sessions)."

addedInput schema / properties / sort / description

Added value: +"Row order: newest first, largest win first, or largest loss first (the default)."

addedInput schema / properties / table_size / description

Added value: +"Only hands dealt at tables of this many seats."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "description": "Hands this account has uploaded.",
+  "properties": {
+    "gto": {
+      "description": "Always \"not graded\": solver grades are not attached.",
+      "type": "string"
+    },
+    "gtoNote": {
+      "description": "Why a solver-grade filter matches nothing.",
+      "type": "string"
+    },
+    "hands": {
+      "description": "Matching hands, sorted as requested.",
+      "items": {
+        "description": "One uploaded hand.",
+        "properties": {
+          "board": {
+            "description": "Board as dealt.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "cards": {
+            "description": "Hero's hole cards.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "flop": {
+            "description": "Flop action lines.",
+            "items": {
+              "description": "One flop action line.",
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "game": {
+            "description": "Game type: \"NLHE\", \"PLO\", \"PLO5\", or \"PLO6\".",
+            "type": "string"
+          },
+          "gto_plo5_rfi_bucket": {
+            "description": "Solver grade bucket. Not filled: grades are not computed.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "gto_status": {
+            "description": "Always \"not_graded\": no solver frequency is attached to uploaded hands.",
+            "type": "string"
+          },
+          "gto_vs_3bet_bucket": {
+            "description": "Solver grade bucket. Not filled: grades are not computed.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "handAt": {
+            "description": "Hand timestamp as written in the history.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "hand_id": {
+            "description": "Stable id for this hand.",
+            "type": "string"
+          },
+          "netBb": {
+            "description": "Hero's result in big blinds.",
+            "type": "number"
+          },
+          "position": {
+            "description": "Hero's seat, e.g. BTN.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "potType": {
+            "description": "Preflop pot type, e.g. \"srp\" or \"3bet\".",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "preflop": {
+            "description": "Preflop action lines.",
+            "items": {
+              "description": "One preflop action line.",
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "river": {
+            "description": "River action lines.",
+            "items": {
+              "description": "One river action line.",
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "session_id": {
+            "description": "Upload session the hand came from.",
+            "type": "string"
+          },
+          "source_hand_id": {
+            "description": "Hand id printed by the original site.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "table_size": {
+            "description": "Seats at the table.",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "timezone": {
+            "description": "Timezone label from the history.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "turn": {
+            "description": "Turn action lines.",
+            "items": {
+              "description": "One turn action line.",
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "vsThreeBetAction": {
+            "description": "Hero's action facing a 3-bet: \"fold\", \"call\", or \"raise\".",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "hint": {
+      "description": "Where to upload hands when the account has none.",
+      "type": "string"
+    },
+    "returned": {
+      "description": "Hands in this response.",
+      "type": "integer"
+    },
+    "total": {
+      "description": "Matching hands before the limit.",
+      "type": "integer"
+    }
+  },
+  "type": "object"
+}

First observedOct 16, 2026

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive), so the bar is lower. The description still adds real behavioral value: solver grade buckets are not filled, and the explicit fallback when the account has no hands. It omits pagination/truncation behavior and the fact that sort defaults to biggest_loss.

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?

Three sentences, front-loaded with the core purpose before details, with no filler. The enumeration of return fields is long but useful; the grade-bucket sentence is partly redundant with the schema descriptions.

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?

With an output schema present, return values need not be explained, yet the key behavioral edge cases (empty account, unfilled grade buckets affecting the gto_* filters) are covered. An agent has enough to call it correctly and handle the zero-result path.

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 sort, limit, filter fields, and both gto bucket params. The description's note that grade buckets 'are not filled' restates the schema's own caveat rather than adding new meaning. 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+resource and scopes it precisely ('hands the account has uploaded'), then enumerates the returned fields (hand_id, session_id, handAt, position, cards, game, board, potType, street lines, netBb). It does not explicitly contrast with the nearest sibling (list_my_sessions, get_hand_results), but the scope is unambiguous.

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 a concrete routing rule for the empty-result case: offer get_upload_link's hosted upload page rather than asking the user to paste histories into chat. That names an alternative tool and the condition that selects it, though it offers no guidance on when to prefer this over sibling retrieval tools in the normal case.

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

All PokerData tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?