Borgo is an MCP server published by io.github.ABCastor, hosted at borgo.abcastor.com. When last checked on 2026-11-22 it was working: it answers and lists its tools. It declares 11 tools, including search_cities, get_city, compare_cities, suggest_cities, net_pay.
Compare cities to live in on open, sourced data: take-home pay, rent, visas, climate, safety.
Nothing else in the archive shares these values.
Find cities already in the dataset (the snapshot and places fetched before) by name, alias or id, optionally within one country. Returns ids for the other tools, how many match and whether more do. This server holds Borgo's published cities; any other place needs the local server (npx -y @abcastor/borgo mcp) and its fetch_city.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Default 10 for a query, 100 for the full list |
| query * | string | Name, alias or id; empty lists every city |
| country | string | ISO alpha-2 filter |
None yet. Changes appear after a server's second daily check.
Squares are this server's values; dots are other servers sharing them. A shared address or publisher is a lead, not proof of a common operator.
Inferred from the host name and headers: what a server runs on, not who runs it.
{
"name": "search_cities",
"title": "Search cities",
"description": "Find cities already in the dataset (the snapshot and places fetched before) by name, alias or id, optionally within one country. Returns ids for the other tools, how many match and whether more do. This server holds Borgo's published cities; any other place needs the local server (npx -y @abcastor/borgo mcp) and its fetch_city.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"query"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Default 10 for a query, 100 for the full list"
},
"query": {
"type": "string",
"description": "Name, alias or id; empty lists every city"
},
"country": {
"type": "string",
"description": "ISO alpha-2 filter"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"reportVersion",
"total",
"hasMore",
"cities"
],
"properties": {
"total": {
"type": "number",
"description": "Cities that match"
},
"cities": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"country"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"country": {
"type": "string"
}
},
"additionalProperties": {}
}
},
"hasMore": {
"type": "boolean"
},
"reportVersion": {
"type": "string",
"description": "The report's shape version (now 2.0)"
}
},
"additionalProperties": {}
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}One city's figures, each with source, period, geographic level and licence; daylight; the take-home pay model; whether each person in a household may live and work there, with the rules checked; links to sources we may not copy, and Borgo's generic quality-of-life index with its fixed weights. Compact by default (figures with a value, long series counted); pass metrics for a few figures, detail "full" for everything.
| Parameter | Type | Description |
|---|---|---|
| city * | string | City id or name |
| detail | string | "summary" (default) or "full" |
| rights | array | Optional: each person's rights to live and work that are not citizenship, in the same order as passports, e.g. [[{kind:'permanent',where:'DE'}]] |
| metrics | array | Only these metric ids, e.g. ['rent_1bed','pm25']; list_metrics_and_sources kind "metrics" lists them |
| passports | array | Optional: each person's passports, e.g. [['US']] or [['IT'],['US','IE']]: who may live and work there |
{
"name": "get_city",
"title": "Figures for a city",
"description": "One city's figures, each with source, period, geographic level and licence; daylight; the take-home pay model; whether each person in a household may live and work there, with the rules checked; links to sources we may not copy, and Borgo's generic quality-of-life index with its fixed weights. Compact by default (figures with a value, long series counted); pass metrics for a few figures, detail \"full\" for everything.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"city"
],
"properties": {
"city": {
"type": "string",
"description": "City id or name"
},
"detail": {
"enum": [
"summary",
"full"
],
"type": "string",
"description": "\"summary\" (default) or \"full\""
},
"rights": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"where"
],
"properties": {
"kind": {
"enum": [
"permanent",
"settled",
"residence",
"work",
"blue-card",
"other"
],
"type": "string",
"description": "permanent: Permanent residence (a green card, Niederlassungserlaubnis, EU long-term residence, indefinite leave to remain); settled: Settled status (the UK's EU Settlement Scheme); residence: Residence permit (a residence card as a family member, a permit for self-employment); work: Work visa or permit (an H-1B, a Skilled Worker visa, a Critical Skills permit); blue-card: EU Blue Card (the EU's permit for highly qualified work); other: Other right to live and work (a treaty right, a youth mobility visa)"
},
"work": {
"type": "boolean",
"description": "false when it allows living there but not working; default true"
},
"until": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Its last valid day, YYYY-MM-DD; leave out for a right without an end"
},
"where": {
"type": "string",
"description": "Where it holds: a country, ISO alpha-2 (DE), or a free-movement area id (EEA) for a right granted across it"
}
}
}
},
"description": "Optional: each person's rights to live and work that are not citizenship, in the same order as passports, e.g. [[{kind:'permanent',where:'DE'}]]"
},
"metrics": {
"type": "array",
"items": {
"type": "string"
},
"description": "Only these metric ids, e.g. ['rent_1bed','pm25']; list_metrics_and_sources kind \"metrics\" lists them"
},
"passports": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Optional: each person's passports, e.g. [['US']] or [['IT'],['US','IE']]: who may live and work there"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"reportVersion",
"detail",
"note",
"city",
"figures",
"rights"
],
"properties": {
"city": {
"type": "object",
"required": [
"id",
"name",
"country"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"country": {
"type": "string"
}
},
"additionalProperties": {}
},
"note": {
"type": [
"string",
"null"
]
},
"detail": {
"enum": [
"summary",
"full"
],
"type": "string"
},
"rights": {
"type": "array",
"items": {
"type": "object",
"required": [
"person",
"status",
"text"
],
"properties": {
"text": {
"type": "string"
},
"person": {
"type": "string"
},
"status": {
"enum": [
"yes",
"no",
"unknown"
],
"type": "string"
}
},
"additionalProperties": {}
}
},
"figures": {
"type": "array",
"items": {
"type": "object",
"required": [
"metric"
],
"properties": {
"metric": {
"type": "string"
}
},
"additionalProperties": {}
}
},
"reportVersion": {
"type": "string",
"description": "The report's shape version (now 2.0)"
}
},
"additionalProperties": {}
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Rank any number of cities for a person or household: a verdict, the score out of 100 from their weights with points and reasons per line, must-pass lines as pass, fail or unknown, each earner's take-home pay and what is left after rent and spending, who can move there, how the set was scored, and what to add next. Every figure carries its source and period. Compact by default; detail "full" adds every tax line, childcare, health, leave and break-even.
| Parameter | Type | Description |
|---|---|---|
| only | array | Score only these criteria; every other line gets weight 0 (each listed one keeps its `weights` value, else 100). For a one-line question: only ["nice_days"] with comfort {min:20,max:28} |
| work | string | The person's kind of work, only if they said it: software (Software and IT), engineering (Engineering, not software), science (Research and science), medicine (Doctors and dentists), nursing (Nursing and care), teaching (Teaching and education), finance (Finance and accounting), law (Law), marketing… |
| limit | integer | How many ranked cities to describe in the summary (default 10); the ranking counts the rest |
| cities * | array | City ids (e.g. turin-it) or names in any common spelling (Turin, Torino, 'Paris, FR'); a name two places share needs its country |
| detail | string | "summary" (default): verdict, ranking, weighted lines with citations, money in brief, who can move there, notes, required unknowns and next inputs. "full": every line, tax line and source, for programs |
| preset | string | Starting weights |
| salary | object | Your gross yearly salary, the same everywhere |
| comfort | object | Weather: what a nice day is, for criterion nice_days: the daytime temperature range, °C (default 18-30 on the feels-like temperature; basis "air" uses the air in the shade), then the tests a day must pass. Only the person's own words: rain and sky are on unless they drop them; humidity, wind and day… |
| housing | string | one of ["1bed","3bed"] |
| missing | string | In fixed scoring, missing lines do not count for that city. Only with opt-in relative scoring: lowest scores gaps at the lowest compared score, worst at 0, skip drops the line for all. Money is never imputed |
| pension | number | Share of your gross paid into a pension, 0.05 = 5%: it leaves take-home pay and is shown as saving, not cost. Tax relief is modelled for CA (RRSP), CH (pillar 3a), CZ (pension savings (penzijní spoření)), DE (occupational pension (Entgeltumwandlung)), EE (third pillar), ES (plan de pensiones), FR (P… |
| regimes | object | Newcomer tax regime per country, ISO alpha-2 -> regime id from list_metrics_and_sources. None counts unless named here; a named one is a scenario until the person's facts and confirmations meet every condition |
| savings | number | Savings in the display currency, for runway |
| stances | object | Where the person stands on the position lines, which score a place by its distance from them: politics 0 (left) to 10 (right); abortion 0 not allowed or only to save her life, 1 also for her health or after rape, 2 also on social or economic grounds, 3 on request in the first weeks only, 4 on reques… |
| weights | object | Weight 0-100 per criterion, on top of the preset. Criteria: money_left, living_cost, right_to_live, nice_days, winter_light, sunshine, dry_days, clean_air, safety, long_life, health_costs, childcare, family_leave, happiness, builders, field_pay, field_jobs, young_companies, time_zone, flight_home, a… |
| children | array | Children's ages: childcare after public support for under-6s (OECD), child credits and allowances where the tax uses them, health for each person |
| personal | array | Your own 1-5 lines, scores keyed by city |
| spending | object | Monthly spending on everything except housing, childcare and health, which are counted separately |
| household | array | Everyone moving, you first. Anyone after you can bring their own pay; a spouse counts for joint filing even with none |
| normalise | string | Default absolute: fixed city-local scores. Relative is opt-in: adding cities can change other scores, gap handling and the shared money basis. |
| overrides | object | Your own numbers: city -> metric id -> value; money in the city's currency. health_premium is the household's premium a month (prefer healthPremium, which takes the period); childcare_cost is the household's own childcare a month (prefer childcareCost); childcare_net_couple_1 and similar replace the… |
| taxTweaks | object | Per-country tax tweaks keyed by ISO alpha-2 |
| dealBreakers | array | Must-pass criterion ids, e.g. right_to_live, money_left: a city fails, passes, or is unknown (no figure, no passport or other right given); unknown ranks after every city that passes |
| salaryByCity | object | Gross yearly salary per city (offers or estimates), keyed by city id or name |
| childcareCost | object | What the household actually pays for childcare in a city, after support, keyed by city id or name, in the city's currency, with per "month" or "year": replaces the OECD reference figure |
| healthPremium | object | The household's health insurance premium bought outside pay (US, CH, NL), keyed by city id or name, in the city's currency, with per "month" or "year" (a year is counted as a twelfth a month) |
| paidChildcare | boolean | Whether the household pays for childcare for its children under 6 (default true). false: no childcare cost is counted. Ask when it matters: the default prices full-time care for an OECD reference household |
| displayCurrency | string | Currency to show amounts in (default: the salary's, else EUR) |
{
"name": "compare_cities",
"title": "Compare cities",
"description": "Rank any number of cities for a person or household: a verdict, the score out of 100 from their weights with points and reasons per line, must-pass lines as pass, fail or unknown, each earner's take-home pay and what is left after rent and spending, who can move there, how the set was scored, and what to add next. Every figure carries its source and period. Compact by default; detail \"full\" adds every tax line, childcare, health, leave and break-even.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cities"
],
"properties": {
"only": {
"type": "array",
"items": {
"type": "string"
},
"description": "Score only these criteria; every other line gets weight 0 (each listed one keeps its `weights` value, else 100). For a one-line question: only [\"nice_days\"] with comfort {min:20,max:28}"
},
"work": {
"enum": [
"software",
"engineering",
"science",
"medicine",
"nursing",
"teaching",
"finance",
"law",
"marketing",
"office",
"sales",
"hospitality",
"trades",
"transport",
"public",
"management",
"founder"
],
"type": "string",
"description": "The person's kind of work, only if they said it: software (Software and IT), engineering (Engineering, not software), science (Research and science), medicine (Doctors and dentists), nursing (Nursing and care), teaching (Teaching and education), finance (Finance and accounting), law (Law), marketing (Marketing, design and media), office (Office and administration), sales (Sales and retail), hospitality (Hospitality and food), trades (Construction and trades), transport (Transport and logistics), public (Public sector), management (Management), founder (Founding a company). Adds what people in that work earn there and how many jobs its field holds to Work and ambition, and shares the group's weight by the kind's recipe (founder: young companies, developers, graduates); each city then says why in plain sentences (work). Leave out for the same Work and ambition as everyone"
},
"limit": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "How many ranked cities to describe in the summary (default 10); the ranking counts the rest"
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "City ids (e.g. turin-it) or names in any common spelling (Turin, Torino, 'Paris, FR'); a name two places share needs its country"
},
"detail": {
"enum": [
"summary",
"full"
],
"type": "string",
"description": "\"summary\" (default): verdict, ranking, weighted lines with citations, money in brief, who can move there, notes, required unknowns and next inputs. \"full\": every line, tax line and source, for programs"
},
"preset": {
"enum": [
"balanced",
"founder",
"family",
"saver"
],
"type": "string",
"description": "Starting weights"
},
"salary": {
"type": "object",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "number",
"description": "Amount"
},
"currency": {
"type": "string",
"description": "ISO 4217, e.g. EUR, GBP, USD. Default: the display currency"
}
},
"description": "Your gross yearly salary, the same everywhere"
},
"comfort": {
"type": "object",
"required": [
"min",
"max"
],
"properties": {
"dry": {
"type": "boolean",
"description": "Under 1 mm of rain from 8 am to 8 pm (default true; false lets rain through)"
},
"max": {
"type": "number"
},
"min": {
"type": "number"
},
"calm": {
"type": "boolean",
"description": "Calm: the daytime wind under 20 km/h on average (default false)"
},
"basis": {
"enum": [
"feels",
"air"
],
"type": "string"
},
"clear": {
"type": "boolean",
"description": "At most half the sky clouded on average from 8 am to 8 pm, the sunshine test (default true)"
},
"daylight": {
"type": "number",
"maximum": 24,
"minimum": 0,
"description": "At least this many hours of daylight, from the latitude (default none)"
},
"notMuggy": {
"type": "boolean",
"description": "Not muggy: the day's mean dew point under 18 °C (default false)"
}
},
"description": "Weather: what a nice day is, for criterion nice_days: the daytime temperature range, °C (default 18-30 on the feels-like temperature; basis \"air\" uses the air in the shade), then the tests a day must pass. Only the person's own words: rain and sky are on unless they drop them; humidity, wind and daylight only when they ask. All from ERA5 (Open-Meteo, CC BY 4.0) and the latitude"
},
"housing": {
"enum": [
"1bed",
"3bed"
],
"type": "string"
},
"missing": {
"enum": [
"lowest",
"skip",
"worst"
],
"type": "string",
"description": "In fixed scoring, missing lines do not count for that city. Only with opt-in relative scoring: lowest scores gaps at the lowest compared score, worst at 0, skip drops the line for all. Money is never imputed"
},
"pension": {
"type": "number",
"maximum": 0.5,
"minimum": 0,
"description": "Share of your gross paid into a pension, 0.05 = 5%: it leaves take-home pay and is shown as saving, not cost. Tax relief is modelled for CA (RRSP), CH (pillar 3a), CZ (pension savings (penzijní spoření)), DE (occupational pension (Entgeltumwandlung)), EE (third pillar), ES (plan de pensiones), FR (PER (plan d'épargne retraite)), GB (workplace or personal pension), HU (voluntary pension fund), IE (occupational pension or PRSA), IT (fondo pensione), JP (iDeCo), NL (workplace pension), NO (IPS (individual pension savings)), PT (PPR), SG (SRS), US (401(k)); elsewhere it is not modelled and the share is counted as saving with no relief (each city's money says which)"
},
"regimes": {
"type": "object",
"description": "Newcomer tax regime per country, ISO alpha-2 -> regime id from list_metrics_and_sources. None counts unless named here; a named one is a scenario until the person's facts and confirmations meet every condition",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"savings": {
"type": "number",
"description": "Savings in the display currency, for runway"
},
"stances": {
"type": "object",
"description": "Where the person stands on the position lines, which score a place by its distance from them: politics 0 (left) to 10 (right); abortion 0 not allowed or only to save her life, 1 also for her health or after rape, 2 also on social or economic grounds, 3 on request in the first weeks only, 4 on request to 10 weeks or later; couples_law 0 criminalised (same-sex relations a crime), 1 legal with no union in law, 2 civil union or partnership, 3 marriage. Pass only what the person told you or what you know they hold; never guess. A stance counts once its line has a weight (they are 0 by default)",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"number",
"string"
]
}
},
"weights": {
"type": "object",
"description": "Weight 0-100 per criterion, on top of the preset. Criteria: money_left, living_cost, right_to_live, nice_days, winter_light, sunshine, dry_days, clean_air, safety, long_life, health_costs, childcare, family_leave, happiness, builders, field_pay, field_jobs, young_companies, time_zone, flight_home, airport, public_transport, rail, short_commute, cycling, walkable, active_commute, way_out, sea, mountains, green, internet, english, international, doctors, jobs, degrees, developers, qol, clean_government, politics, abortion, couples_law, founders_run, coworking, climbing, swimming, beach, run_ride, muggy, grey, hot_nights, heat, snow, wind",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number",
"maximum": 100,
"minimum": 0
}
},
"children": {
"type": "array",
"items": {
"type": "number",
"maximum": 29,
"minimum": 0
},
"description": "Children's ages: childcare after public support for under-6s (OECD), child credits and allowances where the tax uses them, health for each person"
},
"personal": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"scores"
],
"properties": {
"label": {
"type": "string"
},
"scores": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number",
"maximum": 5,
"minimum": 1
}
}
}
},
"description": "Your own 1-5 lines, scores keyed by city"
},
"spending": {
"type": "object",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "number",
"description": "Amount"
},
"currency": {
"type": "string",
"description": "ISO 4217, e.g. EUR, GBP, USD. Default: the display currency"
},
"homeCity": {
"type": "string",
"description": "Where you spend this today; default: the first city"
}
},
"description": "Monthly spending on everything except housing, childcare and health, which are counted separately"
},
"household": {
"type": "array",
"items": {
"type": "object",
"properties": {
"age": {
"type": "integer",
"maximum": 110,
"minimum": 14,
"description": "Age in years: age-dependent tax (youth relief, care insurance), pension caps, paid leave, newcomer regimes"
},
"label": {
"type": "string"
},
"rights": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"where"
],
"properties": {
"kind": {
"enum": [
"permanent",
"settled",
"residence",
"work",
"blue-card",
"other"
],
"type": "string",
"description": "permanent: Permanent residence (a green card, Niederlassungserlaubnis, EU long-term residence, indefinite leave to remain); settled: Settled status (the UK's EU Settlement Scheme); residence: Residence permit (a residence card as a family member, a permit for self-employment); work: Work visa or permit (an H-1B, a Skilled Worker visa, a Critical Skills permit); blue-card: EU Blue Card (the EU's permit for highly qualified work); other: Other right to live and work (a treaty right, a youth mobility visa)"
},
"work": {
"type": "boolean",
"description": "false when it allows living there but not working; default true"
},
"until": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Its last valid day, YYYY-MM-DD; leave out for a right without an end"
},
"where": {
"type": "string",
"description": "Where it holds: a country, ISO alpha-2 (DE), or a free-movement area id (EEA) for a right granted across it"
}
}
},
"description": "Rights to live and work this person holds that are not citizenship, only if they told you: permanent residence (a green card, indefinite leave to remain), settled status, a residence permit, a work visa, an EU Blue Card. Each has a kind, where it holds (a country or a free-movement area id such as EEA), and its last valid day if it ends. A permit counts until that day; one that ended, or bars work (work: false), does not"
},
"salary": {
"type": "object",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "number",
"description": "Amount"
},
"currency": {
"type": "string",
"description": "ISO 4217, e.g. EUR, GBP, USD. Default: the display currency"
}
},
"description": "Not for the first person (use `salary`): this person's gross yearly pay, the same everywhere"
},
"spouse": {
"type": "boolean",
"description": "Married to (or registered partner of) the first person: joint filing where the country has it, applied when it is required or cheaper"
},
"pension": {
"type": "number",
"maximum": 0.5,
"minimum": 0,
"description": "This person's pension share of gross, 0.05 = 5%"
},
"regimes": {
"type": "object",
"description": "Not for the first person (use `regimes`): newcomer regimes this person chose, ISO alpha-2 -> regime id, checked against this person's own facts and confirmations; a scenario until they meet every condition",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"relation": {
"enum": [
"partner",
"cofounder",
"family"
],
"type": "string",
"description": "Partner decides couple vs single-parent childcare"
},
"passports": {
"type": "array",
"items": {
"type": "string"
},
"description": "ISO alpha-2 codes, e.g. ['IT','US'], if known. Leave out when you do not know them: that person's right to live there is then reported as not checked, never as needing a visa"
},
"entryRoutes": {
"type": "object",
"description": "Country to route id, only if conditions are confirmed: GB gb-ancestry (Commonwealth citizenship, eligible grandparent, support and work), gb-skilled (sponsored eligible job, salary and English); US us-h1b (cap-subject employer petition). Rough guide, not legal advice; other routes are not checked.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"salaryByCity": {
"type": "object",
"description": "Not for the first person: this person's gross per city, keyed by city id or name",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "number",
"description": "Amount"
},
"currency": {
"type": "string",
"description": "ISO 4217, e.g. EUR, GBP, USD. Default: the display currency"
}
}
}
},
"yearsSinceResident": {
"type": "object",
"description": "Whole years since last tax resident there, by ISO alpha-2, or 'never': for newcomer regimes",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "string",
"const": "never"
}
]
}
},
"regimeConfirmations": {
"type": "object",
"description": "This person's answers to newcomer-regime conditions no dataset can check, by condition id (list_metrics_and_sources kind \"regimes\"), e.g. {\"nl-recruited-abroad\": true}. Only what the person told you",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "boolean"
}
}
}
},
"description": "Everyone moving, you first. Anyone after you can bring their own pay; a spouse counts for joint filing even with none"
},
"normalise": {
"enum": [
"absolute",
"relative"
],
"type": "string",
"description": "Default absolute: fixed city-local scores. Relative is opt-in: adding cities can change other scores, gap handling and the shared money basis."
},
"overrides": {
"type": "object",
"description": "Your own numbers: city -> metric id -> value; money in the city's currency. health_premium is the household's premium a month (prefer healthPremium, which takes the period); childcare_cost is the household's own childcare a month (prefer childcareCost); childcare_net_couple_1 and similar replace the OECD reference figure, a year",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
}
},
"taxTweaks": {
"type": "object",
"description": "Per-country tax tweaks keyed by ISO alpha-2",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"note": {
"type": "string"
},
"flatRate": {
"type": "number",
"maximum": 1,
"minimum": 0,
"description": "Flat income tax rate replacing the schedule, e.g. 0.24"
},
"taxableShare": {
"type": "number",
"maximum": 1,
"minimum": 0,
"description": "Share of gross that is taxable, e.g. 0.5 under an impatriate regime"
},
"noSocialContributions": {
"type": "boolean",
"description": "You pay none of the country's employee social contributions, e.g. a foreigner on a Singapore Employment Pass pays no CPF"
}
}
}
},
"dealBreakers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Must-pass criterion ids, e.g. right_to_live, money_left: a city fails, passes, or is unknown (no figure, no passport or other right given); unknown ranks after every city that passes"
},
"salaryByCity": {
"type": "object",
"description": "Gross yearly salary per city (offers or estimates), keyed by city id or name",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "number",
"description": "Amount"
},
"currency": {
"type": "string",
"description": "ISO 4217, e.g. EUR, GBP, USD. Default: the display currency"
}
}
}
},
"childcareCost": {
"type": "object",
"description": "What the household actually pays for childcare in a city, after support, keyed by city id or name, in the city's currency, with per \"month\" or \"year\": replaces the OECD reference figure",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"required": [
"amount",
"per"
],
"properties": {
"per": {
"enum": [
"month",
"year"
],
"type": "string",
"description": "What the amount is for: a month or a year"
},
"amount": {
"type": "number",
"minimum": 0,
"description": "Amount, in the city's own currency"
}
}
}
},
"healthPremium": {
"type": "object",
"description": "The household's health insurance premium bought outside pay (US, CH, NL), keyed by city id or name, in the city's currency, with per \"month\" or \"year\" (a year is counted as a twelfth a month)",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"required": [
"amount",
"per"
],
"properties": {
"per": {
"enum": [
"month",
"year"
],
"type": "string",
"description": "What the amount is for: a month or a year"
},
"amount": {
"type": "number",
"minimum": 0,
"description": "Amount, in the city's own currency"
}
}
}
},
"paidChildcare": {
"type": "boolean",
"description": "Whether the household pays for childcare for its children under 6 (default true). false: no childcare cost is counted. Ask when it matters: the default prices full-time care for an OECD reference household"
},
"displayCurrency": {
"type": "string",
"description": "Currency to show amounts in (default: the salary's, else EUR)"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"reportVersion",
"detail",
"verdict",
"provisional",
"provisionalReasons",
"moneyBasis",
"notes",
"requiredUnknowns",
"assumptions",
"ranking",
"cities",
"displayCurrency"
],
"properties": {
"notes": {
"type": "array",
"items": {
"type": "string"
},
"description": "How this set was scored: a line on another basis or left out for every city, periods that differ"
},
"cities": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"rank"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"rank": {
"type": "number"
}
},
"additionalProperties": {}
}
},
"detail": {
"enum": [
"summary",
"full"
],
"type": "string"
},
"ranking": {
"type": "array",
"items": {
"type": "object",
"required": [
"rank",
"id",
"name",
"total",
"coverage",
"status",
"unresolved",
"ruledOut"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"rank": {
"type": "number"
},
"total": {
"type": "number",
"description": "Score out of 100"
},
"status": {
"enum": [
"passes",
"unknown",
"ruled out"
],
"type": "string",
"description": "Must-pass outcome"
},
"coverage": {
"type": "number",
"description": "Share of the weight scored on observed figures, 0-1"
},
"ruledOut": {
"type": "array",
"items": {
"type": "string"
}
},
"unresolved": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": {}
}
},
"verdict": {
"type": "string",
"description": "Who leads, qualified when a must-pass is unknown, when the lead is provisional, and when money was compared on another basis"
},
"moneyBasis": {
"anyOf": [
{
"type": "object",
"required": [
"requested",
"used"
],
"properties": {
"used": {
"type": "string"
},
"requested": {
"type": "string"
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The money line asked for and the basis it was compared on for every city"
},
"assumptions": {
"type": "array",
"items": {
"type": "string"
}
},
"provisional": {
"type": "boolean",
"description": "True when missing figures, partial money or money compared on another basis could still change who leads: say so"
},
"reportVersion": {
"type": "string",
"description": "The report's shape version (now 2.0)"
},
"displayCurrency": {
"type": "string"
},
"requiredUnknowns": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"lines"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"lines": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": {}
}
},
"provisionalReasons": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": {}
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Rank all published cities by the current profile: top five not already in cities, with their two biggest observed score contributions. Same inputs as compare_cities; cities may be empty. Fixed scoring by default; Weather uses your nice-day definition. Missing lines do not count there: check coverage before deciding.
| Parameter | Type | Description |
|---|---|---|
| only | array | Score only these criteria; every other line gets weight 0 (each listed one keeps its `weights` value, else 100). For a one-line question: only ["nice_days"] with comfort {min:20,max:28} |
| work | string | The person's kind of work, only if they said it: software (Software and IT), engineering (Engineering, not software), science (Research and science), medicine (Doctors and dentists), nursing (Nursing and care), teaching (Teaching and education), finance (Finance and accounting), law (Law), marketing… |
| limit | integer | How many ranked cities to describe in the summary (default 10); the ranking counts the rest |
| cities | array | Already chosen cities to exclude, if any |
| detail | string | "summary" (default): verdict, ranking, weighted lines with citations, money in brief, who can move there, notes, required unknowns and next inputs. "full": every line, tax line and source, for programs |
| preset | string | Starting weights |
| salary | object | Your gross yearly salary, the same everywhere |
| comfort | object | Weather: what a nice day is, for criterion nice_days: the daytime temperature range, °C (default 18-30 on the feels-like temperature; basis "air" uses the air in the shade), then the tests a day must pass. Only the person's own words: rain and sky are on unless they drop them; humidity, wind and day… |
| housing | string | one of ["1bed","3bed"] |
| missing | string | In fixed scoring, missing lines do not count for that city. Only with opt-in relative scoring: lowest scores gaps at the lowest compared score, worst at 0, skip drops the line for all. Money is never imputed |
| pension | number | Share of your gross paid into a pension, 0.05 = 5%: it leaves take-home pay and is shown as saving, not cost. Tax relief is modelled for CA (RRSP), CH (pillar 3a), CZ (pension savings (penzijní spoření)), DE (occupational pension (Entgeltumwandlung)), EE (third pillar), ES (plan de pensiones), FR (P… |
| regimes | object | Newcomer tax regime per country, ISO alpha-2 -> regime id from list_metrics_and_sources. None counts unless named here; a named one is a scenario until the person's facts and confirmations meet every condition |
| savings | number | Savings in the display currency, for runway |
| stances | object | Where the person stands on the position lines, which score a place by its distance from them: politics 0 (left) to 10 (right); abortion 0 not allowed or only to save her life, 1 also for her health or after rape, 2 also on social or economic grounds, 3 on request in the first weeks only, 4 on reques… |
| weights | object | Weight 0-100 per criterion, on top of the preset. Criteria: money_left, living_cost, right_to_live, nice_days, winter_light, sunshine, dry_days, clean_air, safety, long_life, health_costs, childcare, family_leave, happiness, builders, field_pay, field_jobs, young_companies, time_zone, flight_home, a… |
| children | array | Children's ages: childcare after public support for under-6s (OECD), child credits and allowances where the tax uses them, health for each person |
| personal | array | Your own 1-5 lines, scores keyed by city |
| spending | object | Monthly spending on everything except housing, childcare and health, which are counted separately |
| household | array | Everyone moving, you first. Anyone after you can bring their own pay; a spouse counts for joint filing even with none |
| normalise | string | Default absolute: fixed city-local scores. Relative is opt-in: adding cities can change other scores, gap handling and the shared money basis. |
| overrides | object | Your own numbers: city -> metric id -> value; money in the city's currency. health_premium is the household's premium a month (prefer healthPremium, which takes the period); childcare_cost is the household's own childcare a month (prefer childcareCost); childcare_net_couple_1 and similar replace the… |
| taxTweaks | object | Per-country tax tweaks keyed by ISO alpha-2 |
| dealBreakers | array | Must-pass criterion ids, e.g. right_to_live, money_left: a city fails, passes, or is unknown (no figure, no passport or other right given); unknown ranks after every city that passes |
| salaryByCity | object | Gross yearly salary per city (offers or estimates), keyed by city id or name |
| childcareCost | object | What the household actually pays for childcare in a city, after support, keyed by city id or name, in the city's currency, with per "month" or "year": replaces the OECD reference figure |
| healthPremium | object | The household's health insurance premium bought outside pay (US, CH, NL), keyed by city id or name, in the city's currency, with per "month" or "year" (a year is counted as a twelfth a month) |
| paidChildcare | boolean | Whether the household pays for childcare for its children under 6 (default true). false: no childcare cost is counted. Ask when it matters: the default prices full-time care for an OECD reference household |
| displayCurrency | string | Currency to show amounts in (default: the salary's, else EUR) |
{
"name": "suggest_cities",
"title": "Suggest cities for me",
"description": "Rank all published cities by the current profile: top five not already in cities, with their two biggest observed score contributions. Same inputs as compare_cities; cities may be empty. Fixed scoring by default; Weather uses your nice-day definition. Missing lines do not count there: check coverage before deciding.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"only": {
"type": "array",
"items": {
"type": "string"
},
"description": "Score only these criteria; every other line gets weight 0 (each listed one keeps its `weights` value, else 100). For a one-line question: only [\"nice_days\"] with comfort {min:20,max:28}"
},
"work": {
"enum": [
"software",
"engineering",
"science",
"medicine",
"nursing",
"teaching",
"finance",
"law",
"marketing",
"office",
"sales",
"hospitality",
"trades",
"transport",
"public",
"management",
"founder"
],
"type": "string",
"description": "The person's kind of work, only if they said it: software (Software and IT), engineering (Engineering, not software), science (Research and science), medicine (Doctors and dentists), nursing (Nursing and care), teaching (Teaching and education), finance (Finance and accounting), law (Law), marketing (Marketing, design and media), office (Office and administration), sales (Sales and retail), hospitality (Hospitality and food), trades (Construction and trades), transport (Transport and logistics), public (Public sector), management (Management), founder (Founding a company). Adds what people in that work earn there and how many jobs its field holds to Work and ambition, and shares the group's weight by the kind's recipe (founder: young companies, developers, graduates); each city then says why in plain sentences (work). Leave out for the same Work and ambition as everyone"
},
"limit": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "How many ranked cities to describe in the summary (default 10); the ranking counts the rest"
},
"cities": {
"type": "array",
"items": {
"type": "string"
},
"description": "Already chosen cities to exclude, if any"
},
"detail": {
"enum": [
"summary",
"full"
],
"type": "string",
"description": "\"summary\" (default): verdict, ranking, weighted lines with citations, money in brief, who can move there, notes, required unknowns and next inputs. \"full\": every line, tax line and source, for programs"
},
"preset": {
"enum": [
"balanced",
"founder",
"family",
"saver"
],
"type": "string",
"description": "Starting weights"
},
"salary": {
"type": "object",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "number",
"description": "Amount"
},
"currency": {
"type": "string",
"description": "ISO 4217, e.g. EUR, GBP, USD. Default: the display currency"
}
},
"description": "Your gross yearly salary, the same everywhere"
},
"comfort": {
"type": "object",
"required": [
"min",
"max"
],
"properties": {
"dry": {
"type": "boolean",
"description": "Under 1 mm of rain from 8 am to 8 pm (default true; false lets rain through)"
},
"max": {
"type": "number"
},
"min": {
"type": "number"
},
"calm": {
"type": "boolean",
"description": "Calm: the daytime wind under 20 km/h on average (default false)"
},
"basis": {
"enum": [
"feels",
"air"
],
"type": "string"
},
"clear": {
"type": "boolean",
"description": "At most half the sky clouded on average from 8 am to 8 pm, the sunshine test (default true)"
},
"daylight": {
"type": "number",
"maximum": 24,
"minimum": 0,
"description": "At least this many hours of daylight, from the latitude (default none)"
},
"notMuggy": {
"type": "boolean",
"description": "Not muggy: the day's mean dew point under 18 °C (default false)"
}
},
"description": "Weather: what a nice day is, for criterion nice_days: the daytime temperature range, °C (default 18-30 on the feels-like temperature; basis \"air\" uses the air in the shade), then the tests a day must pass. Only the person's own words: rain and sky are on unless they drop them; humidity, wind and daylight only when they ask. All from ERA5 (Open-Meteo, CC BY 4.0) and the latitude"
},
"housing": {
"enum": [
"1bed",
"3bed"
],
"type": "string"
},
"missing": {
"enum": [
"lowest",
"skip",
"worst"
],
"type": "string",
"description": "In fixed scoring, missing lines do not count for that city. Only with opt-in relative scoring: lowest scores gaps at the lowest compared score, worst at 0, skip drops the line for all. Money is never imputed"
},
"pension": {
"type": "number",
"maximum": 0.5,
"minimum": 0,
"description": "Share of your gross paid into a pension, 0.05 = 5%: it leaves take-home pay and is shown as saving, not cost. Tax relief is modelled for CA (RRSP), CH (pillar 3a), CZ (pension savings (penzijní spoření)), DE (occupational pension (Entgeltumwandlung)), EE (third pillar), ES (plan de pensiones), FR (PER (plan d'épargne retraite)), GB (workplace or personal pension), HU (voluntary pension fund), IE (occupational pension or PRSA), IT (fondo pensione), JP (iDeCo), NL (workplace pension), NO (IPS (individual pension savings)), PT (PPR), SG (SRS), US (401(k)); elsewhere it is not modelled and the share is counted as saving with no relief (each city's money says which)"
},
"regimes": {
"type": "object",
"description": "Newcomer tax regime per country, ISO alpha-2 -> regime id from list_metrics_and_sources. None counts unless named here; a named one is a scenario until the person's facts and confirmations meet every condition",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"savings": {
"type": "number",
"description": "Savings in the display currency, for runway"
},
"stances": {
"type": "object",
"description": "Where the person stands on the position lines, which score a place by its distance from them: politics 0 (left) to 10 (right); abortion 0 not allowed or only to save her life, 1 also for her health or after rape, 2 also on social or economic grounds, 3 on request in the first weeks only, 4 on request to 10 weeks or later; couples_law 0 criminalised (same-sex relations a crime), 1 legal with no union in law, 2 civil union or partnership, 3 marriage. Pass only what the person told you or what you know they hold; never guess. A stance counts once its line has a weight (they are 0 by default)",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"number",
"string"
]
}
},
"weights": {
"type": "object",
"description": "Weight 0-100 per criterion, on top of the preset. Criteria: money_left, living_cost, right_to_live, nice_days, winter_light, sunshine, dry_days, clean_air, safety, long_life, health_costs, childcare, family_leave, happiness, builders, field_pay, field_jobs, young_companies, time_zone, flight_home, airport, public_transport, rail, short_commute, cycling, walkable, active_commute, way_out, sea, mountains, green, internet, english, international, doctors, jobs, degrees, developers, qol, clean_government, politics, abortion, couples_law, founders_run, coworking, climbing, swimming, beach, run_ride, muggy, grey, hot_nights, heat, snow, wind",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number",
"maximum": 100,
"minimum": 0
}
},
"children": {
"type": "array",
"items": {
"type": "number",
"maximum": 29,
"minimum": 0
},
"description": "Children's ages: childcare after public support for under-6s (OECD), child credits and allowances where the tax uses them, health for each person"
},
"personal": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"scores"
],
"properties": {
"label": {
"type": "string"
},
"scores": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number",
"maximum": 5,
"minimum": 1
}
}
}
},
"description": "Your own 1-5 lines, scores keyed by city"
},
"spending": {
"type": "object",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "number",
"description": "Amount"
},
"currency": {
"type": "string",
"description": "ISO 4217, e.g. EUR, GBP, USD. Default: the display currency"
},
"homeCity": {
"type": "string",
"description": "Where you spend this today; default: the first city"
}
},
"description": "Monthly spending on everything except housing, childcare and health, which are counted separately"
},
"household": {
"type": "array",
"items": {
"type": "object",
"properties": {
"age": {
"type": "integer",
"maximum": 110,
"minimum": 14,
"description": "Age in years: age-dependent tax (youth relief, care insurance), pension caps, paid leave, newcomer regimes"
},
"label": {
"type": "string"
},
"rights": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"where"
],
"properties": {
"kind": {
"enum": [
"permanent",
"settled",
"residence",
"work",
"blue-card",
"other"
],
"type": "string",
"description": "permanent: Permanent residence (a green card, Niederlassungserlaubnis, EU long-term residence, indefinite leave to remain); settled: Settled status (the UK's EU Settlement Scheme); residence: Residence permit (a residence card as a family member, a permit for self-employment); work: Work visa or permit (an H-1B, a Skilled Worker visa, a Critical Skills permit); blue-card: EU Blue Card (the EU's permit for highly qualified work); other: Other right to live and work (a treaty right, a youth mobility visa)"
},
"work": {
"type": "boolean",
"description": "false when it allows living there but not working; default true"
},
"until": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Its last valid day, YYYY-MM-DD; leave out for a right without an end"
},
"where": {
"type": "string",
"description": "Where it holds: a country, ISO alpha-2 (DE), or a free-movement area id (EEA) for a right granted across it"
}
}
},
"description": "Rights to live and work this person holds that are not citizenship, only if they told you: permanent residence (a green card, indefinite leave to remain), settled status, a residence permit, a work visa, an EU Blue Card. Each has a kind, where it holds (a country or a free-movement area id such as EEA), and its last valid day if it ends. A permit counts until that day; one that ended, or bars work (work: false), does not"
},
"salary": {
"type": "object",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "number",
"description": "Amount"
},
"currency": {
"type": "string",
"description": "ISO 4217, e.g. EUR, GBP, USD. Default: the display currency"
}
},
"description": "Not for the first person (use `salary`): this person's gross yearly pay, the same everywhere"
},
"spouse": {
"type": "boolean",
"description": "Married to (or registered partner of) the first person: joint filing where the country has it, applied when it is required or cheaper"
},
"pension": {
"type": "number",
"maximum": 0.5,
"minimum": 0,
"description": "This person's pension share of gross, 0.05 = 5%"
},
"regimes": {
"type": "object",
"description": "Not for the first person (use `regimes`): newcomer regimes this person chose, ISO alpha-2 -> regime id, checked against this person's own facts and confirmations; a scenario until they meet every condition",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"relation": {
"enum": [
"partner",
"cofounder",
"family"
],
"type": "string",
"description": "Partner decides couple vs single-parent childcare"
},
"passports": {
"type": "array",
"items": {
"type": "string"
},
"description": "ISO alpha-2 codes, e.g. ['IT','US'], if known. Leave out when you do not know them: that person's right to live there is then reported as not checked, never as needing a visa"
},
"entryRoutes": {
"type": "object",
"description": "Country to route id, only if conditions are confirmed: GB gb-ancestry (Commonwealth citizenship, eligible grandparent, support and work), gb-skilled (sponsored eligible job, salary and English); US us-h1b (cap-subject employer petition). Rough guide, not legal advice; other routes are not checked.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"salaryByCity": {
"type": "object",
"description": "Not for the first person: this person's gross per city, keyed by city id or name",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "number",
"description": "Amount"
},
"currency": {
"type": "string",
"description": "ISO 4217, e.g. EUR, GBP, USD. Default: the display currency"
}
}
}
},
"yearsSinceResident": {
"type": "object",
"description": "Whole years since last tax resident there, by ISO alpha-2, or 'never': for newcomer regimes",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"anyOf": [
{
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
{
"type": "string",
"const": "never"
}
]
}
},
"regimeConfirmations": {
"type": "object",
"description": "This person's answers to newcomer-regime conditions no dataset can check, by condition id (list_metrics_and_sources kind \"regimes\"), e.g. {\"nl-recruited-abroad\": true}. Only what the person told you",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "boolean"
}
}
}
},
"description": "Everyone moving, you first. Anyone after you can bring their own pay; a spouse counts for joint filing even with none"
},
"normalise": {
"enum": [
"absolute",
"relative"
],
"type": "string",
"description": "Default absolute: fixed city-local scores. Relative is opt-in: adding cities can change other scores, gap handling and the shared money basis."
},
"overrides": {
"type": "object",
"description": "Your own numbers: city -> metric id -> value; money in the city's currency. health_premium is the household's premium a month (prefer healthPremium, which takes the period); childcare_cost is the household's own childcare a month (prefer childcareCost); childcare_net_couple_1 and similar replace the OECD reference figure, a year",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
}
},
"taxTweaks": {
"type": "object",
"description": "Per-country tax tweaks keyed by ISO alpha-2",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"note": {
"type": "string"
},
"flatRate": {
"type": "number",
"maximum": 1,
"minimum": 0,
"description": "Flat income tax rate replacing the schedule, e.g. 0.24"
},
"taxableShare": {
"type": "number",
"maximum": 1,
"minimum": 0,
"description": "Share of gross that is taxable, e.g. 0.5 under an impatriate regime"
},
"noSocialContributions": {
"type": "boolean",
"description": "You pay none of the country's employee social contributions, e.g. a foreigner on a Singapore Employment Pass pays no CPF"
}
}
}
},
"dealBreakers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Must-pass criterion ids, e.g. right_to_live, money_left: a city fails, passes, or is unknown (no figure, no passport or other right given); unknown ranks after every city that passes"
},
"salaryByCity": {
"type": "object",
"description": "Gross yearly salary per city (offers or estimates), keyed by city id or name",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "number",
"description": "Amount"
},
"currency": {
"type": "string",
"description": "ISO 4217, e.g. EUR, GBP, USD. Default: the display currency"
}
}
}
},
"childcareCost": {
"type": "object",
"description": "What the household actually pays for childcare in a city, after support, keyed by city id or name, in the city's currency, with per \"month\" or \"year\": replaces the OECD reference figure",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"required": [
"amount",
"per"
],
"properties": {
"per": {
"enum": [
"month",
"year"
],
"type": "string",
"description": "What the amount is for: a month or a year"
},
"amount": {
"type": "number",
"minimum": 0,
"description": "Amount, in the city's own currency"
}
}
}
},
"healthPremium": {
"type": "object",
"description": "The household's health insurance premium bought outside pay (US, CH, NL), keyed by city id or name, in the city's currency, with per \"month\" or \"year\" (a year is counted as a twelfth a month)",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"required": [
"amount",
"per"
],
"properties": {
"per": {
"enum": [
"month",
"year"
],
"type": "string",
"description": "What the amount is for: a month or a year"
},
"amount": {
"type": "number",
"minimum": 0,
"description": "Amount, in the city's own currency"
}
}
}
},
"paidChildcare": {
"type": "boolean",
"description": "Whether the household pays for childcare for its children under 6 (default true). false: no childcare cost is counted. Ask when it matters: the default prices full-time care for an OECD reference household"
},
"displayCurrency": {
"type": "string",
"description": "Currency to show amounts in (default: the salary's, else EUR)"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"reportVersion"
],
"properties": {
"reportVersion": {
"type": "string",
"description": "The report's shape version (now 2.0)"
}
},
"additionalProperties": {}
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Take-home pay for a gross yearly salary in a country (and region or city, for regional and municipal taxes), with every tax line, the model's caveats and its official sources. Takes age, children, a pension share, a newcomer regime, and a partner (joint filing for a married couple where the country has it).
| Parameter | Type | Description |
|---|---|---|
| age | integer | Age in years, where the tax uses it |
| city | string | City id or name; sets country, region and municipal taxes |
| gross * | number | Gross yearly salary |
| tweak | object | |
| regime | string | A newcomer regime id for this country (list_metrics_and_sources kind "regimes") |
| region | string | ISO 3166-2 subdivision, e.g. US-CA, GB-SCT, IT-21 |
| country | string | ISO alpha-2 or name; optional when city is given |
| partner | object | A second earner in the same household |
| pension | number | Pension share of gross, 0.05 = 5% |
| children | array | Children's ages, for child credits and allowances |
| currency | string | Currency of gross; default the country's |
| displayCurrency | string |
{
"name": "net_pay",
"title": "Take-home pay",
"description": "Take-home pay for a gross yearly salary in a country (and region or city, for regional and municipal taxes), with every tax line, the model's caveats and its official sources. Takes age, children, a pension share, a newcomer regime, and a partner (joint filing for a married couple where the country has it).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"gross"
],
"properties": {
"age": {
"type": "integer",
"maximum": 110,
"minimum": 14,
"description": "Age in years, where the tax uses it"
},
"city": {
"type": "string",
"description": "City id or name; sets country, region and municipal taxes"
},
"gross": {
"type": "number",
"description": "Gross yearly salary",
"exclusiveMinimum": 0
},
"tweak": {
"type": "object",
"properties": {
"note": {
"type": "string"
},
"flatRate": {
"type": "number",
"maximum": 1,
"minimum": 0,
"description": "Flat income tax rate replacing the schedule, e.g. 0.24"
},
"taxableShare": {
"type": "number",
"maximum": 1,
"minimum": 0,
"description": "Share of gross that is taxable, e.g. 0.5 under an impatriate regime"
},
"noSocialContributions": {
"type": "boolean",
"description": "You pay none of the country's employee social contributions, e.g. a foreigner on a Singapore Employment Pass pays no CPF"
}
}
},
"regime": {
"type": "string",
"description": "A newcomer regime id for this country (list_metrics_and_sources kind \"regimes\")"
},
"region": {
"type": "string",
"description": "ISO 3166-2 subdivision, e.g. US-CA, GB-SCT, IT-21"
},
"country": {
"type": "string",
"description": "ISO alpha-2 or name; optional when city is given"
},
"partner": {
"type": "object",
"required": [
"gross"
],
"properties": {
"age": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991
},
"gross": {
"type": "number",
"minimum": 0,
"description": "Their gross yearly salary, in the same currency as gross; 0 for a spouse with no pay"
},
"spouse": {
"type": "boolean",
"description": "Married or registered partners: joint filing where the country has it"
},
"pension": {
"type": "number",
"maximum": 0.5,
"minimum": 0
}
},
"description": "A second earner in the same household"
},
"pension": {
"type": "number",
"maximum": 0.5,
"minimum": 0,
"description": "Pension share of gross, 0.05 = 5%"
},
"children": {
"type": "array",
"items": {
"type": "number",
"maximum": 29,
"minimum": 0
},
"description": "Children's ages, for child credits and allowances"
},
"currency": {
"type": "string",
"description": "Currency of gross; default the country's"
},
"displayCurrency": {
"type": "string"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"reportVersion",
"country",
"currency",
"gross",
"net",
"effectiveRate",
"lines",
"caveats",
"sources"
],
"properties": {
"net": {
"type": "number"
},
"gross": {
"type": "number"
},
"lines": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"amount"
],
"properties": {
"label": {
"type": "string"
},
"amount": {
"type": "number"
}
},
"additionalProperties": {}
}
},
"caveats": {
"type": "array",
"items": {
"type": "string"
}
},
"country": {
"type": "string"
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"label",
"url"
],
"properties": {
"url": {
"type": "string"
},
"label": {
"type": "string"
}
},
"additionalProperties": {}
}
},
"currency": {
"type": "string"
},
"effectiveRate": {
"type": "number"
},
"reportVersion": {
"type": "string",
"description": "The report's shape version (now 2.0)"
}
},
"additionalProperties": {}
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}What the dataset holds: scoring lines with their scales and default weights, metrics with coverage, sources with licences, take-home pay models, newcomer regimes with each condition's id, presets, and the link-only sources. Pass kind for one part (kind "regimes", country "NL" lists the Dutch regimes and their conditions).
| Parameter | Type | Description |
|---|---|---|
| kind | string | One part only; leave out for everything |
| country | string | ISO alpha-2, with kind taxModels or regimes |
{
"name": "list_metrics_and_sources",
"title": "Metrics, criteria and sources",
"description": "What the dataset holds: scoring lines with their scales and default weights, metrics with coverage, sources with licences, take-home pay models, newcomer regimes with each condition's id, presets, and the link-only sources. Pass kind for one part (kind \"regimes\", country \"NL\" lists the Dutch regimes and their conditions).",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"kind": {
"enum": [
"criteria",
"metrics",
"sources",
"taxModels",
"regimes",
"presets",
"linkOnly",
"pensions"
],
"type": "string",
"description": "One part only; leave out for everything"
},
"country": {
"type": "string",
"description": "ISO alpha-2, with kind taxModels or regimes"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"reportVersion"
],
"properties": {
"reportVersion": {
"type": "string",
"description": "The report's shape version (now 2.0)"
}
},
"additionalProperties": {}
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}How scores, weights, must-pass lines, missing data, the money model, the right to live and the open-data rule work, with every scale.
No parameters.
{
"name": "methodology",
"title": "How the scores and money are computed",
"description": "How scores, weights, must-pass lines, missing data, the money model, the right to live and the open-data rule work, with every scale.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"reportVersion"
],
"properties": {
"reportVersion": {
"type": "string",
"description": "The report's shape version (now 2.0)"
}
},
"additionalProperties": {}
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}The curated list of sources: what each measures (with a plain definition), coverage, licence, whether it may be redistributed, how it is fetched (endpoint, CORS, key) and who vetted it, plus link-only pages such as Numbeo and WeatherSpark. Filter by metric or country; pass a place to get the publisher's page for it.
| Parameter | Type | Description |
|---|---|---|
| city | string | A city id or name in the dataset, to fill in each publisher's page for it |
| access | string | one of ["api","bulk","curated","link-out"] |
| metric | string | Metric id, e.g. pm25, rent_1bed, sunshine_hours |
| country | string | ISO alpha-2: only sources covering this country |
{
"name": "list_sources",
"title": "The source registry",
"description": "The curated list of sources: what each measures (with a plain definition), coverage, licence, whether it may be redistributed, how it is fetched (endpoint, CORS, key) and who vetted it, plus link-only pages such as Numbeo and WeatherSpark. Filter by metric or country; pass a place to get the publisher's page for it.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"city": {
"type": "string",
"description": "A city id or name in the dataset, to fill in each publisher's page for it"
},
"access": {
"enum": [
"api",
"bulk",
"curated",
"link-out"
],
"type": "string"
},
"metric": {
"type": "string",
"description": "Metric id, e.g. pm25, rent_1bed, sunshine_hours"
},
"country": {
"type": "string",
"description": "ISO alpha-2: only sources covering this country"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"reportVersion"
],
"properties": {
"reportVersion": {
"type": "string",
"description": "The report's shape version (now 2.0)"
}
},
"additionalProperties": {}
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Figures people report for themselves about a place on Borgo, after automated review: rent by bedrooms and area, everyday prices, take-home pay by kind of work and a 1 to 5 rating of living there, each with its median (a rating: mean), middle half from 3 entries, count, months and the official figure beside it where one exists. Community data, CC BY 4.0; never mixed into official figures or scores. Covers the snapshot's cities and the towns on Borgo's map.
| Parameter | Type | Description |
|---|---|---|
| city * | string | City id (turin-it) or name ('Turin', 'Palermo, IT') |
{
"name": "community_figures",
"title": "What people report for a place",
"description": "Figures people report for themselves about a place on Borgo, after automated review: rent by bedrooms and area, everyday prices, take-home pay by kind of work and a 1 to 5 rating of living there, each with its median (a rating: mean), middle half from 3 entries, count, months and the official figure beside it where one exists. Community data, CC BY 4.0; never mixed into official figures or scores. Covers the snapshot's cities and the towns on Borgo's map.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"city"
],
"properties": {
"city": {
"type": "string",
"description": "City id (turin-it) or name ('Turin', 'Palermo, IT')"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"reportVersion"
],
"properties": {
"reportVersion": {
"type": "string",
"description": "The report's shape version (now 2.0)"
}
},
"additionalProperties": {}
},
"annotations": {
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}Send what the person pays and earns where they live to Borgo's open community data (published rounded under CC BY 4.0, no name or address kept; an automated review holds amounts far from others' or the official figure). Without confirm it sends nothing and returns the draft with its privacy note: show both to the person. Call again with confirm true only after they said yes to these exact figures, and only figures they gave you as their own, never estimates or figures read on another site. The answer carries a removal code for them to keep.
| Parameter | Type | Description |
|---|---|---|
| city * | string | City id (turin-it) or name ('Turin', 'Palermo, IT') |
| rent | object | |
| prices | object | What they pay for everyday things, in the place's currency |
| rating | integer | Living there, all things considered, 1 poor to 5 excellent |
| salary | object | |
| confirm | boolean | true only after the person agreed to send these exact figures |
| currency | string | ISO 4217; must be the place's own (checked) |
{
"name": "submit_figures",
"title": "Add the person's own figures",
"description": "Send what the person pays and earns where they live to Borgo's open community data (published rounded under CC BY 4.0, no name or address kept; an automated review holds amounts far from others' or the official figure). Without confirm it sends nothing and returns the draft with its privacy note: show both to the person. Call again with confirm true only after they said yes to these exact figures, and only figures they gave you as their own, never estimates or figures read on another site. The answer carries a removal code for them to keep.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"city"
],
"properties": {
"city": {
"type": "string",
"description": "City id (turin-it) or name ('Turin', 'Palermo, IT')"
},
"rent": {
"type": "object",
"required": [
"amount",
"bedrooms",
"area"
],
"properties": {
"area": {
"enum": [
"centre",
"outside"
],
"type": "string",
"description": "centre or outside the centre"
},
"amount": {
"type": "number",
"minimum": 0,
"description": "What they pay a month, without bills, in the place's currency"
},
"bedrooms": {
"enum": [
"0",
"1",
"2",
"3"
],
"type": "string",
"description": "0: Studio; 1: 1 bedroom; 2: 2 bedrooms; 3: 3 or more bedrooms"
}
}
},
"prices": {
"type": "object",
"properties": {
"gym": {
"type": "number",
"minimum": 0,
"description": "Gym membership, a month"
},
"meal": {
"type": "number",
"minimum": 0,
"description": "Meal at an inexpensive restaurant, one meal"
},
"milk": {
"type": "number",
"minimum": 0,
"description": "Milk, 1 litre, 1 litre"
},
"transit": {
"type": "number",
"minimum": 0,
"description": "Monthly public transport pass, a month"
},
"internet": {
"type": "number",
"minimum": 0,
"description": "Home internet, a month"
},
"cappuccino": {
"type": "number",
"minimum": 0,
"description": "Cappuccino in a café, one cup"
}
},
"description": "What they pay for everyday things, in the place's currency"
},
"rating": {
"type": "integer",
"maximum": 5,
"minimum": 1,
"description": "Living there, all things considered, 1 poor to 5 excellent"
},
"salary": {
"type": "object",
"required": [
"amount",
"occupation"
],
"properties": {
"amount": {
"type": "number",
"minimum": 0,
"description": "What they take home a month after tax"
},
"occupation": {
"enum": [
"software",
"engineering",
"science",
"medicine",
"nursing",
"teaching",
"finance",
"law",
"marketing",
"office",
"sales",
"hospitality",
"trades",
"transport",
"public",
"management",
"other"
],
"type": "string",
"description": "software: Software and IT; engineering: Engineering, not software; science: Research and science; medicine: Doctors and dentists; nursing: Nursing and care; teaching: Teaching and education; finance: Finance and accounting; law: Law; marketing: Marketing, design and media; office: Office and administration; sales: Sales and retail; hospitality: Hospitality and food; trades: Construction and trades; transport: Transport and logistics; public: Public sector; management: Management; other: Other work"
}
}
},
"confirm": {
"type": "boolean",
"description": "true only after the person agreed to send these exact figures"
},
"currency": {
"type": "string",
"description": "ISO 4217; must be the place's own (checked)"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"reportVersion"
],
"properties": {
"reportVersion": {
"type": "string",
"description": "The report's shape version (now 2.0)"
}
},
"additionalProperties": {}
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}
}Delete a submission the person sent, with the removal code it gave them.
| Parameter | Type | Description |
|---|---|---|
| code * | string | The 20-character removal code |
{
"name": "remove_figures",
"title": "Take back a submission",
"description": "Delete a submission the person sent, with the removal code it gave them.",
"inputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"description": "The 20-character removal code"
}
}
},
"outputSchema": {
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"reportVersion"
],
"properties": {
"reportVersion": {
"type": "string",
"description": "The report's shape version (now 2.0)"
}
},
"additionalProperties": {}
},
"annotations": {
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": true
}
}Borgo compares cities to live in on open, sourced data, weighted by the person's own values, and works out take-home pay and what is left after rent and everyday spending. Use it for any question about where to live, relocating or moving abroad, comparing cities, cost of living, rent, take-home pay or net salary in another country, quality of life, climate or air quality of a city, or whether someone's passports let them live and work there. How to use it well: - suggest_cities ranks all published cities for the current profile and returns five not already chosen, with their two biggest observed reasons; missing figures can favour thinly covered cities, so check coverage. - compare_cities is the main tool. Pass the cities and only what the person told you: passports and any other right to live and work they hold, such as permanent residence, a work visa or an EU Blue Card (household; leave a person's passports out when you do not know them, and that person's right to live and work there is reported as not checked), salary or per-city offers with currency, a partner's pay and whether they are married, ages, children's ages, a pension share, monthly spending and where they live now (this unlocks the break-even salary), housing size, what matters to them (a preset, explicit weights 0-100, or `only` for a one-line question such as only: ["nice_days"]), must-pass lines (dealBreakers), their own 1-5 lines. Never invent a salary, spending or passports: leave them out and relay "what to add next". - Answers are compact by default (detail "summary", the top 10 cities). Ask for detail "full" only when the person wants every tax line and source; use `limit` for long lists. - Lead with the verdict and its qualifiers: a must-pass that cannot be checked is "unknown" and is never a pass; in default fixed scoring, a missing line does not count for that city, and adding another city never changes its score. Required lines filter without taking any score share. Money's fallback basis is city-local and named in notes. Relative scoring is opt-in. Relay the notes, the required unknowns and the next inputs. - This server answers for Borgo's published cities (search_cities lists them, with their ids). Any other place needs Borgo's local server (npx -y @abcastor/borgo mcp), whose fetch_city fetches any real place into the person's own cache: suggest it when a place is missing. - Link-only sources (Numbeo, WeatherSpark and the other pages list_sources marks link-out) forbid copying and automated reading: never fetch or read them yourself. Give the person the link. - Each call's arguments reach Borgo's server only to compute that answer: it keeps none of them and counts only how many calls each tool gets. Nothing goes on to other providers. Send only what the person told you. - search_cities finds ids (a miss means the place is not in the published data); get_city gives a city's figures with source, period, level and licence (pass `metrics` for a few, `passports` for who may live there); net_pay answers take-home pay questions on their own; list_metrics_and_sources (filter with `kind`, e.g. kind "regimes" and country "NL") and methodology explain what the scores mean. - Position lines (politics, abortion, couples_law) are stances, not more-is-better: pass a stance only when the person stated it or you already know it from them, never from their nationality, city or any other guess, and give the line a weight. Report each place's fact in neutral words, with its date. - When the person says what work they do, pass `work` (e.g. "software", "founder"): Work and ambition then counts what that work pays there, how many jobs its field holds and, for founders, how many young companies are around, and each city carries plain sentences saying why (cities[].work). Relay them. Pay in the field is a guide; take-home pay still uses the salary they give. - get_city includes Borgo's generic quality-of-life index (qualityOfLife): fixed weights shown, the same for eve
Names, descriptions and schemas were written by the server and are shown as data.