{"openapi":"3.1.0","info":{"title":"Tipworld API","version":"0.1.0","description":"A hand-curated, cross-referenced reference of real tipping customs (restaurants, taxis, hotels, tour guides) for 40 countries across every populated continent, with a tip calculator, country comparison, region browsing, service-charge-included flags, cultural notes and a glossary. Compiled and cross-checked against multiple published travel/consumer sources; norms vary and evolve, and every answer says so.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://tipworld.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/tipworld/docs"},"termsOfService":"https://connectorbay.com/tipworld/terms"},"servers":[{"url":"https://tipworld.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/tipworld/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/tipping_norms":{"post":{"operationId":"tipping_norms","summary":"Tipping norms for one country — restaurant, taxi/rideshare, hotel and tour-guide guidance, whether a service","description":"Tipping norms for one country — restaurant, taxi/rideshare, hotel and tour-guide guidance, whether a service\n    charge is typically already included, the overall norm category, and a cultural note. Pass service_type to get\n    just that one field. Use for \"how much should I tip in Japan\", \"is tipping expected in Italy\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country":{"description":"A country name.","examples":["Japan","Mexico","United Kingdom"],"minLength":1,"title":"Country","type":"string"},"service_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optional: 'restaurant', 'taxi', 'hotel' or 'tour_guide'. Omit for the full country record.","title":"Service Type"}},"required":["country"],"title":"tipping_normsArguments","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_countries":{"post":{"operationId":"compare_countries","summary":"Lines up several countries' tipping norms for one service type side by side. Use for \"compare restaurant","description":"Lines up several countries' tipping norms for one service type side by side. Use for \"compare restaurant\n    tipping in the US, France and Japan\", \"how does taxi tipping differ between Mexico and Canada\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"countries":{"description":"2-10 country names to compare.","items":{"type":"string"},"maxItems":10,"minItems":2,"title":"Countries","type":"array"},"service_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"'restaurant' (default), 'taxi', 'hotel' or 'tour_guide'.","title":"Service Type"}},"required":["countries"],"title":"compare_countriesArguments","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/calculate_tip":{"post":{"operationId":"calculate_tip","summary":"Suggests a tip amount for a bill in a given country and service type, using that country's typical","description":"Suggests a tip amount for a bill in a given country and service type, using that country's typical\n    percentage range where the norm is percentage-based (some countries' norms are flat amounts or 'not\n    customary' instead — those are noted rather than forced into a percentage). Use for \"what's a fair tip on a\n    $60 dinner in Mexico\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country":{"description":"A country name.","examples":["United States"],"minLength":1,"title":"Country","type":"string"},"bill_amount":{"description":"The bill total.","examples":[60],"exclusiveMinimum":0,"title":"Bill Amount","type":"number"},"service_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"'restaurant' (default), 'taxi', 'hotel' or 'tour_guide'.","title":"Service Type"}},"required":["country","bill_amount"],"title":"calculate_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/countries_list":{"post":{"operationId":"countries_list","summary":"Every country Tipworld covers, with its overall tipping-norm category. Use for \"what countries do you","description":"Every country Tipworld covers, with its overall tipping-norm category. Use for \"what countries do you\n    cover\", \"do you have tipping info for Croatia\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"countries_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/region_list":{"post":{"operationId":"region_list","summary":"Every region Tipworld covers with the countries in it. Use for \"what regions do you have tipping data","description":"Every region Tipworld covers with the countries in it. Use for \"what regions do you have tipping data\n    for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"region_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/countries_by_region":{"post":{"operationId":"countries_by_region","summary":"Lists a specific region's countries with their overall tipping norm. Use for \"what countries in Asia do you","description":"Lists a specific region's countries with their overall tipping norm. Use for \"what countries in Asia do you\n    cover and how do their norms compare broadly\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"A region name.","examples":["Europe","Asia","Middle East"],"minLength":1,"title":"Region","type":"string"}},"required":["region"],"title":"countries_by_regionArguments","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/service_charge_info":{"post":{"operationId":"service_charge_info","summary":"Whether a service charge is typically already included on the bill in a country — the single most common","description":"Whether a service charge is typically already included on the bill in a country — the single most common\n    cause of accidental double-tipping. Use for \"is service charge included in restaurants in the UAE\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country":{"description":"A country name.","minLength":1,"title":"Country","type":"string"}},"required":["country"],"title":"service_charge_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/cultural_notes":{"post":{"operationId":"cultural_notes","summary":"The short cultural context for tipping in a country — why it's a core expected part of pay in some places","description":"The short cultural context for tipping in a country — why it's a core expected part of pay in some places\n    and can read as confusing or even mildly rude in others. Use for \"why is tipping considered rude in Japan\",\n    \"why do Americans tip so much\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country":{"description":"A country name.","minLength":1,"title":"Country","type":"string"}},"required":["country"],"title":"cultural_notesArguments","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/glossary":{"post":{"operationId":"glossary","summary":"Definitions of tipping-related terms — service charge, gratuity, cover charge, baksheesh, tipflation,","description":"Definitions of tipping-related terms — service charge, gratuity, cover charge, baksheesh, tipflation,\n    service compris. Use for \"what's the difference between a service charge and a gratuity\", \"what does baksheesh\n    mean\".","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":"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}}}}