{"openapi":"3.1.0","info":{"title":"Dice Combo API","version":"0.1.0","description":"A real, stateless, playable category dice-scoring game (roll up to 3 times per turn, score into one of 13 open categories) with genuine scoring math and an AI opponent. Every tool call takes the full game state and returns the new state; nothing is stored server-side.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://dicecombo.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/dicecombo/docs"},"termsOfService":"https://connectorbay.com/dicecombo/terms"},"servers":[{"url":"https://dicecombo.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/dicecombo/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/new_game":{"post":{"operationId":"new_game","summary":"Starts a fresh game: empty scorecards for each player, first roll of 5 dice already made.","description":"Starts a fresh game: empty scorecards for each player, first roll of 5 dice already made.\n    Use for \"let's play a dice game\", \"new game\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"players":{"default":["human","ai"],"description":"1-2 player names/labels, e.g. ['human', 'ai'].","items":{"type":"string"},"title":"Players","type":"array"}},"title":"new_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/get_valid_moves":{"post":{"operationId":"get_valid_moves","summary":"Returns whether a reroll is still allowed this turn and which scorecard categories are","description":"Returns whether a reroll is still allowed this turn and which scorecard categories are\n    still open for the current player. Use for \"can I reroll again\", \"what categories are left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game/roll_dice/apply_score.","examples":[{"current_player":0,"dice":[3,3,5,6,1],"held":[false,false,false,false,false],"players":["human","ai"],"rolls_used":1,"scorecards":{"ai":{"chance":null,"five_of_a_kind":null,"fives":null,"four_of_a_kind":null,"fours":null,"full_house":null,"large_straight":null,"ones":null,"sixes":null,"small_straight":null,"three_of_a_kind":null,"threes":null,"twos":null},"human":{"chance":null,"five_of_a_kind":null,"fives":null,"four_of_a_kind":null,"fours":null,"full_house":null,"large_straight":null,"ones":null,"sixes":null,"small_straight":null,"three_of_a_kind":null,"threes":null,"twos":null}},"status":"in_progress","winner":null}],"title":"State","type":"object"}},"required":["state"],"title":"get_valid_movesArguments","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/roll_dice":{"post":{"operationId":"roll_dice","summary":"Rerolls every die not held. Up to 2 rerolls per turn (3 rolls total) -- invalid_move if","description":"Rerolls every die not held. Up to 2 rerolls per turn (3 rolls total) -- invalid_move if\n    already used or the game is over. Use for \"reroll everything except the pair\", \"keep these\n    two, reroll the rest\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game/roll_dice/apply_score.","examples":[{"current_player":0,"dice":[3,3,5,6,1],"held":[false,false,false,false,false],"players":["human","ai"],"rolls_used":1,"scorecards":{"ai":{"chance":null,"five_of_a_kind":null,"fives":null,"four_of_a_kind":null,"fours":null,"full_house":null,"large_straight":null,"ones":null,"sixes":null,"small_straight":null,"three_of_a_kind":null,"threes":null,"twos":null},"human":{"chance":null,"five_of_a_kind":null,"fives":null,"four_of_a_kind":null,"fours":null,"full_house":null,"large_straight":null,"ones":null,"sixes":null,"small_straight":null,"three_of_a_kind":null,"threes":null,"twos":null}},"status":"in_progress","winner":null}],"title":"State","type":"object"},"keep":{"description":"Exactly 5 booleans; true keeps that die, false rerolls it.","examples":[[true,true,false,false,false]],"items":{"type":"boolean"},"title":"Keep","type":"array"}},"required":["state","keep"],"title":"roll_diceArguments","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/apply_score":{"post":{"operationId":"apply_score","summary":"Scores the current dice into one category for the current player (must be still open),","description":"Scores the current dice into one category for the current player (must be still open),\n    ending their turn and advancing to the next player with a fresh roll. status is scored or\n    game_over (state.winner set) once every category is filled for every player. Use for \"score\n    that as three of a kind\", \"take the chance score\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game/roll_dice/apply_score.","examples":[{"current_player":0,"dice":[3,3,5,6,1],"held":[false,false,false,false,false],"players":["human","ai"],"rolls_used":1,"scorecards":{"ai":{"chance":null,"five_of_a_kind":null,"fives":null,"four_of_a_kind":null,"fours":null,"full_house":null,"large_straight":null,"ones":null,"sixes":null,"small_straight":null,"three_of_a_kind":null,"threes":null,"twos":null},"human":{"chance":null,"five_of_a_kind":null,"fives":null,"four_of_a_kind":null,"fours":null,"full_house":null,"large_straight":null,"ones":null,"sixes":null,"small_straight":null,"three_of_a_kind":null,"threes":null,"twos":null}},"status":"in_progress","winner":null}],"title":"State","type":"object"},"category":{"description":"One of: ones, twos, threes, fours, fives, sixes, three_of_a_kind, four_of_a_kind, full_house, small_straight, large_straight, five_of_a_kind, chance.","title":"Category","type":"string"}},"required":["state","category"],"title":"apply_scoreArguments","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/score_category":{"post":{"operationId":"score_category","summary":"Pure calculator: what would `category` score for this exact set of 5 dice? Does not touch","description":"Pure calculator: what would `category` score for this exact set of 5 dice? Does not touch\n    game state. Use for \"what would full house be worth here\", \"how many points is three sixes\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"dice":{"description":"Exactly 5 dice values, 1-6 each.","examples":[[2,2,2,5,5]],"items":{"type":"integer"},"title":"Dice","type":"array"},"category":{"description":"One of: ones, twos, threes, fours, fives, sixes, three_of_a_kind, four_of_a_kind, full_house, small_straight, large_straight, five_of_a_kind, chance.","title":"Category","type":"string"}},"required":["dice","category"],"title":"score_categoryArguments","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/ai_move":{"post":{"operationId":"ai_move","summary":"Recommends (without applying) the AI's next decision: either a reroll ({\"action\": \"reroll\",","description":"Recommends (without applying) the AI's next decision: either a reroll ({\"action\": \"reroll\",\n    \"keep\": [...]}) or a category to score ({\"action\": \"score\", \"category\": ...}), with reasoning.\n    Apply it yourself via `roll_dice` or `apply_score`. Use for \"what should the AI do here\",\n    \"play the AI's turn\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game/roll_dice/apply_score.","examples":[{"current_player":0,"dice":[3,3,5,6,1],"held":[false,false,false,false,false],"players":["human","ai"],"rolls_used":1,"scorecards":{"ai":{"chance":null,"five_of_a_kind":null,"fives":null,"four_of_a_kind":null,"fours":null,"full_house":null,"large_straight":null,"ones":null,"sixes":null,"small_straight":null,"three_of_a_kind":null,"threes":null,"twos":null},"human":{"chance":null,"five_of_a_kind":null,"fives":null,"four_of_a_kind":null,"fours":null,"full_house":null,"large_straight":null,"ones":null,"sixes":null,"small_straight":null,"three_of_a_kind":null,"threes":null,"twos":null}},"status":"in_progress","winner":null}],"title":"State","type":"object"}},"required":["state"],"title":"ai_moveArguments","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/render":{"post":{"operationId":"render","summary":"A human-readable view: current dice and held mask, every player's filled categories and","description":"A human-readable view: current dice and held mask, every player's filled categories and\n    running total (with bonus), and whose turn it is. Use for \"show me the scorecards\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game/roll_dice/apply_score.","examples":[{"current_player":0,"dice":[3,3,5,6,1],"held":[false,false,false,false,false],"players":["human","ai"],"rolls_used":1,"scorecards":{"ai":{"chance":null,"five_of_a_kind":null,"fives":null,"four_of_a_kind":null,"fours":null,"full_house":null,"large_straight":null,"ones":null,"sixes":null,"small_straight":null,"three_of_a_kind":null,"threes":null,"twos":null},"human":{"chance":null,"five_of_a_kind":null,"fives":null,"four_of_a_kind":null,"fours":null,"full_house":null,"large_straight":null,"ones":null,"sixes":null,"small_straight":null,"three_of_a_kind":null,"threes":null,"twos":null}},"status":"in_progress","winner":null}],"title":"State","type":"object"}},"required":["state"],"title":"renderArguments","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/rules":{"post":{"operationId":"rules","summary":"Plain-language rules: every category's scoring, the upper-section bonus, and the AI's","description":"Plain-language rules: every category's scoring, the upper-section bonus, and the AI's\n    strategy. Use for \"how does scoring work\", \"what's the bonus for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"anyOf":[{"additionalProperties":true,"description":"The current game state, exactly as returned by new_game/roll_dice/apply_score.","examples":[{"current_player":0,"dice":[3,3,5,6,1],"held":[false,false,false,false,false],"players":["human","ai"],"rolls_used":1,"scorecards":{"ai":{"chance":null,"five_of_a_kind":null,"fives":null,"four_of_a_kind":null,"fours":null,"full_house":null,"large_straight":null,"ones":null,"sixes":null,"small_straight":null,"three_of_a_kind":null,"threes":null,"twos":null},"human":{"chance":null,"five_of_a_kind":null,"fives":null,"four_of_a_kind":null,"fours":null,"full_house":null,"large_straight":null,"ones":null,"sixes":null,"small_straight":null,"three_of_a_kind":null,"threes":null,"twos":null}},"status":"in_progress","winner":null}],"type":"object"},{"type":"null"}],"default":null,"title":"State"}},"title":"rulesArguments","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}}}}