{"openapi":"3.1.0","info":{"title":"Handrank API","version":"0.1.0","description":"A fully local, hand-curated cross-game card hand-ranking reference: full ordered hand rankings, a real hand-value classifier, head-to-head hand comparison, a cross-game glossary, qualitative rarity notes, and card-point-value tables, spanning poker, gin rummy, 13-card rummy, cribbage, blackjack and contract bridge hand evaluation. Rules and definitions only -- never betting advice.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://handrank.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/handrank/docs"},"termsOfService":"https://connectorbay.com/handrank/terms"},"servers":[{"url":"https://handrank.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/handrank/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/games_list":{"post":{"operationId":"games_list","summary":"Every card game this reference covers, with its id, aliases and a one-line summary of its hand-ranking","description":"Every card game this reference covers, with its id, aliases and a one-line summary of its hand-ranking\n    or hand-evaluation system. Use for \"what games do you cover\", \"list the games\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"games_listArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/ranking_for_game":{"post":{"operationId":"ranking_for_game","summary":"The full ordered hand-ranking or scoring-category list for one game, best to worst, each with a","description":"The full ordered hand-ranking or scoring-category list for one game, best to worst, each with a\n    definition and an example. Use for \"what beats what in poker\", \"what are the cribbage scoring categories\",\n    \"what's the bridge point-count scale\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"game":{"description":"A game name or alias.","examples":["poker","gin rummy","cribbage","blackjack","bridge","rummy"],"minLength":1,"title":"Game","type":"string"}},"required":["game"],"title":"ranking_for_gameArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/hand_value":{"post":{"operationId":"hand_value","summary":"Given a plain description of a hand, identifies what it's called and/or worth in that game's own system,","description":"Given a plain description of a hand, identifies what it's called and/or worth in that game's own system,\n    using real parsing and classification logic (poker hand category with tiebreak info, gin-rummy/rummy meld\n    and deadwood analysis, a full cribbage point breakdown, a blackjack total with soft/hard and bust/natural\n    status, or a bridge high-card-point evaluation) -- not a lookup of exact input strings. Use for \"what is\n    three sevens and a pair of kings called\", \"score this cribbage hand\", \"is this gin rummy hand ready to\n    knock\", \"what's this blackjack hand worth\", \"how strong is this bridge hand\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"game":{"description":"A game name or alias.","examples":["poker","cribbage","gin rummy","blackjack","bridge","rummy"],"minLength":1,"title":"Game","type":"string"},"description":{"description":"A plain-language or notated description of the hand.","examples":["three sevens and a pair of kings","AS KS QS JS 10S","ace and king","spades: A K Q J 5, hearts: K Q 3, diamonds: 8 4, clubs: 9 7 6 2"],"minLength":1,"title":"Description","type":"string"}},"required":["game","description"],"title":"hand_valueArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/compare_hands":{"post":{"operationId":"compare_hands","summary":"Compares two hands for the same game and says which one wins (or ties) and why, using the same","description":"Compares two hands for the same game and says which one wins (or ties) and why, using the same\n    evaluation logic as hand_value. Use for \"which of these two poker hands wins\", \"which of these two bridge\n    hands is stronger\", \"which blackjack hand wins\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"game":{"description":"A game name or alias.","minLength":1,"title":"Game","type":"string"},"hand_a":{"description":"First hand's description, same format as hand_value.","minLength":1,"title":"Hand A","type":"string"},"hand_b":{"description":"Second hand's description, same format as hand_value.","minLength":1,"title":"Hand B","type":"string"}},"required":["game","hand_a","hand_b"],"title":"compare_handsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/term_glossary":{"post":{"operationId":"term_glossary","summary":"Definitions of cross-game and game-specific card terms -- kicker, wheel, deadwood, meld, gin, undercut,","description":"Definitions of cross-game and game-specific card terms -- kicker, wheel, deadwood, meld, gin, undercut,\n    pure sequence, joker/wildcard, fifteen, his nobs, natural, soft/hard hand, bust, push, high card points,\n    balanced hand, void/singleton/doubleton, Yarborough, and more. Use for \"what's a kicker\", \"what does deadwood\n    mean\", \"what's his nobs\", \"what's a Yarborough\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific term to look up; omit to list all.","title":"Term"}},"title":"term_glossaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/probability_note":{"post":{"operationId":"probability_note","summary":"A qualitative (and, where well-established, quantitative) rarity description for a named hand or","description":"A qualitative (and, where well-established, quantitative) rarity description for a named hand or\n    scoring category in a given game. Use for \"how rare is a royal flush\", \"how often does gin happen\", \"how\n    likely is a 29 hand in cribbage\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"game":{"description":"A game name or alias.","minLength":1,"title":"Game","type":"string"},"hand_name":{"description":"A hand or category name from that game's ranking list.","examples":["royal flush","full house","gin","his nobs","natural blackjack","yarborough"],"minLength":1,"title":"Hand Name","type":"string"}},"required":["game","hand_name"],"title":"probability_noteArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/card_point_value":{"post":{"operationId":"card_point_value","summary":"Looks up how a specific card rank is valued in a given game's own counting system: poker's ordinal","description":"Looks up how a specific card rank is valued in a given game's own counting system: poker's ordinal\n    comparison order (2 low through ace high), cribbage/rummy/gin-rummy pip values for building fifteens or\n    deadwood, blackjack's flexible ace, or bridge's Milton Work high-card-point scale. Use for \"what's an ace\n    worth in cribbage\", \"how many high card points is a queen\", \"what does a jack count as in blackjack\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"game":{"description":"A game name or alias.","minLength":1,"title":"Game","type":"string"},"rank":{"description":"A card rank.","examples":["ace","king","7","jack"],"minLength":1,"title":"Rank","type":"string"}},"required":["game","rank"],"title":"card_point_valueArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/find_game_by_mechanic":{"post":{"operationId":"find_game_by_mechanic","summary":"Finds every covered game whose hand-ranking mechanic matches a stated description, keyword-matched","description":"Finds every covered game whose hand-ranking mechanic matches a stated description, keyword-matched\n    against each game's tagged mechanics, summary and goal. Use for \"which games use high card points\", \"what\n    games are about matching sets\", \"which game counts combinations that sum to 15\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"mechanic":{"description":"A mechanic or play style, in plain language.","examples":["matching sets and runs","high card points","counting combinations that sum to a target","flexible ace value","trick taking"],"minLength":1,"title":"Mechanic","type":"string"}},"required":["mechanic"],"title":"find_game_by_mechanicArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}