{"openapi":"3.1.0","info":{"title":"TQ Engine API","version":"0.1.0","description":"A real, playable, fully local Twenty Questions game engine over an original, hand-curated bank of 150 items across 4 categories, each tagged across 29 yes/no attributes. Engine-guesses mode narrows candidates by real information gain; human-guesses mode lets you ask yes/no questions about a secret item. Fully stateless — every tool call passes the full game state.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://tqengine.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/tqengine/docs"},"termsOfService":"https://connectorbay.com/tqengine/terms"},"servers":[{"url":"https://tqengine.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/tqengine/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 new Twenty Questions round in one of two modes and returns the initial `state`. Use for \"let's","description":"Starts a new Twenty Questions round in one of two modes and returns the initial `state`. Use for \"let's\n    play twenty questions\", \"pick an animal and I'll guess it\", \"I'm thinking of something, you guess it\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"mode":{"description":"'engine_guesses' (engine guesses your item) or 'human_guesses' (you guess the engine's secret item).","examples":["engine_guesses","human_guesses"],"title":"Mode","type":"string"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optionally restrict to one category (see list_categories). Omit for any category.","examples":["Animals","Food"],"title":"Category"}},"required":["mode"],"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/next_question":{"post":{"operationId":"next_question","summary":"'engine_guesses' mode only: computes the engine's next move — either the best yes/no question to ask next,","description":"'engine_guesses' mode only: computes the engine's next move — either the best yes/no question to ask next,\n    or (once ready) a guess for you to confirm. Use to advance the engine's turn.","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by a previous call in this connector.","title":"State","type":"object"}},"required":["state"],"title":"next_questionArguments","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/answer_question":{"post":{"operationId":"answer_question","summary":"'engine_guesses' mode only: answers the engine's currently pending question (from next_question) with","description":"'engine_guesses' mode only: answers the engine's currently pending question (from next_question) with\n    yes/no/unsure. Use for \"yes\", \"no\", \"I'm not sure\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by a previous call in this connector.","title":"State","type":"object"},"response":{"description":"Your answer to the engine's pending question.","examples":["yes","no","unsure"],"title":"Response","type":"string"}},"required":["state","response"],"title":"answer_questionArguments","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/confirm_guess":{"post":{"operationId":"confirm_guess","summary":"'engine_guesses' mode only: confirms or rejects the engine's currently pending guess (from","description":"'engine_guesses' mode only: confirms or rejects the engine's currently pending guess (from\n    next_question). Use for \"yes, that's it\", \"no, that's not it\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by a previous call in this connector.","title":"State","type":"object"},"correct":{"description":"Whether the engine's pending guess was correct.","title":"Correct","type":"boolean"}},"required":["state","correct"],"title":"confirm_guessArguments","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/ask_about":{"post":{"operationId":"ask_about","summary":"'human_guesses' mode only: asks the engine, truthfully, whether its secret item has a given attribute.","description":"'human_guesses' mode only: asks the engine, truthfully, whether its secret item has a given attribute.\n    Use for \"does it fly\", \"is it edible\", \"can you eat it\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by a previous call in this connector.","title":"State","type":"object"},"attribute_query":{"description":"An attribute to ask about, in your own words or as an attribute key.","examples":["does it fly","is it edible","has_fur"],"minLength":1,"title":"Attribute Query","type":"string"}},"required":["state","attribute_query"],"title":"ask_aboutArguments","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/guess_item":{"post":{"operationId":"guess_item","summary":"'human_guesses' mode only: guesses the secret item by name. Use for \"is it a dolphin\", \"I guess elephant\".","description":"'human_guesses' mode only: guesses the secret item by name. Use for \"is it a dolphin\", \"I guess elephant\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by a previous call in this connector.","title":"State","type":"object"},"item_name":{"description":"Your guess at the secret item's name.","minLength":1,"title":"Item Name","type":"string"}},"required":["state","item_name"],"title":"guess_itemArguments","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_game":{"post":{"operationId":"render_game","summary":"A human-readable status summary of the current round — this is what to show the player, not the raw","description":"A human-readable status summary of the current round — this is what to show the player, not the raw\n    state (which may hold hidden fields depending on mode).","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"additionalProperties":true,"description":"The current game state, exactly as returned by a previous call in this connector.","title":"State","type":"object"}},"required":["state"],"title":"render_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/list_attributes":{"post":{"operationId":"list_attributes","summary":"Every yes/no attribute this engine's item bank is tagged with, and its exact question text. Use for \"what","description":"Every yes/no attribute this engine's item bank is tagged with, and its exact question text. Use for \"what\n    kinds of questions can you ask/answer\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_attributesArguments","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/list_categories":{"post":{"operationId":"list_categories","summary":"The 4 item categories with item counts. Use for \"what categories do you cover\".","description":"The 4 item categories with item counts. Use for \"what categories do you cover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_categoriesArguments","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/game_rules":{"post":{"operationId":"game_rules","summary":"Explains both game modes, the item bank size, and the information-gain question strategy, with no live","description":"Explains both game modes, the item bank size, and the information-gain question strategy, with no live\n    game needed. Use for \"how does this game work\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"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}}}}