{"openapi":"3.1.0","info":{"title":"Yoyo API","version":"0.1.0","description":"A fully local, hand-curated, original yo-yoing reference: yo-yo types (fixed-axle, transaxle, ball-bearing) and body shapes (standard/imperial, butterfly, modified, organic, H-shape), trick categories described conceptually, competition style divisions 1A-5A, maintenance basics, a terminology glossary, history notes and beginner tips. Keyless; fully local; zero upstream calls.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://yoyo.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/yoyo/docs"},"termsOfService":"https://connectorbay.com/yoyo/terms"},"servers":[{"url":"https://yoyo.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/yoyo/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/yoyo_type_info":{"post":{"operationId":"yoyo_type_info","summary":"Full detail for one yo-yo type or body shape: how it works, pros/cons, and who it suits (beginner,","description":"Full detail for one yo-yo type or body shape: how it works, pros/cons, and who it suits (beginner,\n    intermediate, advanced). Use for \"what's a transaxle yoyo\", \"explain a butterfly shape yoyo\", \"what's an\n    unresponsive yoyo\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A yo-yo type, axle mechanism, or body shape name.","examples":["fixed-axle","unresponsive ball-bearing","butterfly shape","transaxle","offstring"],"minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"yoyo_type_infoArguments","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/trick_category_info":{"post":{"operationId":"trick_category_info","summary":"Conceptual explanation of a yo-yo trick category: what it feels like to play, and what equipment suits","description":"Conceptual explanation of a yo-yo trick category: what it feels like to play, and what equipment suits\n    it. Describes categories in general terms rather than giving step-by-step trick instructions. Use for\n    \"what are slack tricks\", \"explain grinding in yoyo\", \"what's a regen\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A trick category name.","examples":["looping","string tricks","slack tricks","grinds","offstring tricks","freehand tricks"],"minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"trick_category_infoArguments","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/maintenance_tip":{"post":{"operationId":"maintenance_tip","summary":"A practical yo-yo maintenance tip for a named topic — string replacement, string tension, bearing","description":"A practical yo-yo maintenance tip for a named topic — string replacement, string tension, bearing\n    cleaning/lubrication, response pad or silicone replacement, gap width, axle tightness, storage, or\n    cleaning the body — or, with no topic, the full list of topics. Use for \"how do I clean a yoyo bearing\",\n    \"when should I replace my string\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A maintenance topic to look up; omit to list every topic.","examples":["string replacement","bearing cleaning","string tension","gap width"],"title":"Topic"}},"title":"maintenance_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/competition_style_info":{"post":{"operationId":"competition_style_info","summary":"Factual, general description of one of the five recognized competitive yo-yo style divisions — 1A","description":"Factual, general description of one of the five recognized competitive yo-yo style divisions — 1A\n    (single yo-yo string tricks), 2A (looping), 3A (two-handed), 4A (off-string), or 5A (freehand/\n    counterweight) — or, with no name, all five. Exact contest rules vary by organizing body and year. Use\n    for \"what is 4A\", \"explain the 1A yoyo style\", \"what are the yoyo competition divisions\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A competitive style division; omit to list all five.","examples":["1A","2A","looping","offstring","freehand"],"title":"Name"}},"title":"competition_style_infoArguments","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 common yo-yo vocabulary — sleeper, breakaway, bind, gap, response system, regen, grind,","description":"Definitions of common yo-yo vocabulary — sleeper, breakaway, bind, gap, response system, regen, grind,\n    whip, freehand, counterweight, imperial and butterfly shape, and classic named tricks. Use for \"what does\n    'bind' mean in yoyoing\", \"define sleeper\".","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/find_yoyo_type_for_style":{"post":{"operationId":"find_yoyo_type_for_style","summary":"Suggests yo-yo types and shapes suited to a stated skill level (beginner, intermediate, or advanced).","description":"Suggests yo-yo types and shapes suited to a stated skill level (beginner, intermediate, or advanced).\n    Use for \"what yoyo should a beginner get\", \"what type of yoyo suits an intermediate player\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"skill_level":{"description":"A skill level: beginner, intermediate, or advanced.","examples":["beginner","intermediate","advanced"],"minLength":1,"title":"Skill Level","type":"string"}},"required":["skill_level"],"title":"find_yoyo_type_for_styleArguments","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 curated list of yo-yo history notes — origins, key figures, and how equipment evolved over time.","description":"A curated list of yo-yo history notes — origins, key figures, and how equipment evolved over time.\n    Use for \"who invented the yoyo\", \"yoyo history\", \"when did ball-bearing yoyos become common\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"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/beginner_tips":{"post":{"operationId":"beginner_tips","summary":"A ranked shortlist of practical tips for someone just starting to yo-yo — equipment choice, throwing a","description":"A ranked shortlist of practical tips for someone just starting to yo-yo — equipment choice, throwing a\n    clean sleeper, string tension, and more. Use for \"tips for a beginner yoyo player\", \"advice for someone\n    just starting out\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"count":{"default":5,"description":"How many tips to return.","maximum":10,"minimum":1,"title":"Count","type":"integer"}},"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}}}}