{"openapi":"3.1.0","info":{"title":"Folkgame API","version":"0.1.0","description":"A fully local, hand-curated reference for traditional folk and parlor games with no single owner or fixed rulebook: Conkers, Tiddlywinks, Jacks (Knucklebones), Cat's Cradle, Pick-Up Sticks (Jackstraws), Cup-and-Ball (Bilboquet/Kendama family) and Spillikins, with how-to-play steps, history, regional/naming variants, a glossary, DIY equipment tips, beginner tips and group/age suggestions.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://folkgame.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/folkgame/docs"},"termsOfService":"https://connectorbay.com/folkgame/terms"},"servers":[{"url":"https://folkgame.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/folkgame/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/game_rules":{"post":{"operationId":"game_rules","summary":"Full detail for one folk/parlor game: equipment, objective, numbered how-to-play steps, winning","description":"Full detail for one folk/parlor game: equipment, objective, numbered how-to-play steps, winning\n    condition, difficulty, and an honest note on how much rules vary by region and household. Use for \"how\n    do you play conkers\", \"what's the goal of tiddlywinks\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A game's name or alias.","examples":["conkers","tiddlywinks","cat's cradle","spillikins"],"minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"game_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}},"/v1/tools/term_glossary":{"post":{"operationId":"term_glossary","summary":"Definitions of terms specific to these folk games — squidger, wink, squop, onesies, astragalus,","description":"Definitions of terms specific to these folk games — squidger, wink, squop, onesies, astragalus,\n    bilboquet, kendama, jackstraws, mikado, spillikin, and general folk-game vocabulary like 'house rule'.\n    Use for \"what's a squidger\", \"what does onesies mean in jacks\".","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.","examples":["squidger","squop","onesies","bilboquet"],"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/regional_variant":{"post":{"operationId":"regional_variant","summary":"A game's known regional, historical, or naming variants — e.g. bilboquet vs. kendama vs. balero, or","description":"A game's known regional, historical, or naming variants — e.g. bilboquet vs. kendama vs. balero, or\n    knucklebones vs. jacks vs. five stones. These folk games were never standardized, so this list is\n    illustrative, not exhaustive. Use for \"what's the difference between spillikins and pick-up sticks\",\n    \"regional names for cup and ball\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A game's name or alias.","examples":["jacks","cup-and-ball","pick-up sticks"],"minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"regional_variantArguments","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/history_note":{"post":{"operationId":"history_note","summary":"A game's historical background — origins, approximate era, and how it evolved — phrased","description":"A game's historical background — origins, approximate era, and how it evolved — phrased\n    qualitatively wherever exact dates or first records are genuinely uncertain. Use for \"how old is the\n    game of jacks\", \"where does cat's cradle come from\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A game's name or alias.","examples":["conkers","cat's cradle"],"minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"history_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/find_game_for_group":{"post":{"operationId":"find_game_for_group","summary":"Suggests games that fit a given player count and/or a plain-language age description, matched","description":"Suggests games that fit a given player count and/or a plain-language age description, matched\n    against each game's typical group size and age notes. Use for \"what folk game works for 4 kids\", \"a\n    game for one adult who's home alone\", \"something for a mixed-age family gathering\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"player_count":{"anyOf":[{"maximum":20,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many people will play.","examples":[2,4],"title":"Player Count"},"age_range":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A plain-language age description.","examples":["young children","adults","5 and up","all ages"],"title":"Age Range"}},"title":"find_game_for_groupArguments","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/equipment_diy_tip":{"post":{"operationId":"equipment_diy_tip","summary":"How a game's equipment was traditionally made at home from ordinary household or found materials —","description":"How a game's equipment was traditionally made at home from ordinary household or found materials —\n    no purchase required. Use for \"how do you make your own conkers\", \"DIY pick-up sticks\", \"homemade\n    cup-and-ball toy\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A game's name or alias.","examples":["conkers","spillikins"],"minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"equipment_diy_tipArguments","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/category_list":{"post":{"operationId":"category_list","summary":"Every game grouped into its category (Steady-Hand & Precision, Throw-and-Catch, String Figures,","description":"Every game grouped into its category (Steady-Hand & Precision, Throw-and-Catch, String Figures,\n    Contest & Dueling) with a count and the games in each. Use for \"what kinds of folk games do you cover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"category_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/beginner_tips":{"post":{"operationId":"beginner_tips","summary":"A short list of starter tips for a specific game — what to focus on first, common early mistakes to","description":"A short list of starter tips for a specific game — what to focus on first, common early mistakes to\n    avoid. Use for \"tips for a beginner at conkers\", \"how do I get better at jacks\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A game's name or alias.","examples":["tiddlywinks","jacks"],"minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"beginner_tipsArguments","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}}}}