Skip to main content
Glama

cityparity — Cost-of-Living & Quality-of-Life Comparison

Compare two cities for a household

compare_cities
Read-onlyIdempotent

Compare two cities for one household: take-home pay, full cost breakdown, the equivalent target salary needed to match source net cash, non-cash lifestyle deltas (vacation, parental leave, healthcare), and a 0-100 quality score on five weighted dimensions. Use this for a head-to-head between two named cities; for a single city call get_city_summary, and to rank many cities call rank_cities. Read-only, no side effects; returns a text summary plus structured JSON. RSU income is NOT a parameter; RSU is treated as source-only because grants typically do not follow you across employers.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "source_city": "<source_city>",
      "target_city": "<target_city>",
      "gross_salary": "<gross_salary>"
    },
    "name": "compare_cities"
  }
}

Input Schema

NameRequiredDescriptionDefault
livingNoHousing and spending assumptions. Omit to use defaults: rent, 2 bedrooms, typical spending.
advancedNoOptional fine-tuning: retirement contribution, age bracket, trips home, transit mode, and inbound tax regime. Omit to use defaults.
householdNoFamily structure: working-age partner and dependent children. Omit for a single person with no kids.
source_cityYesCity slug for the user's current city. Use list_cities to discover valid slugs (e.g. 'nyc', 'seattle', 'tokyo').
target_cityYesCity slug for the destination city.
gross_salaryYesUser's annual gross salary in the SOURCE city's local currency (e.g. USD for Seattle, NOK for Oslo).
score_weightsNoOverride the composite-score weights. Defaults: financial 30, healthcare 20, vacation 15, childcare 15, safety_net 20.

Output Schema

NameRequiredDescriptionDefault
metaYes
sourceYes
targetYes
equivalenceYes
quality_scoreYes
non_cash_deltasYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / advanced / properties / source_transit_choice / description
      Previous value: -"Default depends on city; e.g. Seattle defaults to 'car', Oslo defaults to 'transit'."New value: +"Default depends on the city, the same rule the cityparity calculator uses: 'car' (the city's annual car-ownership cost) where the metro is car-dependent, 'transit' (a monthly pass per traveller) everywhere else. Seattle defaults to 'car', Oslo and New York to 'transit'."
  2. Changed1 schema field changed
    • changedInput schema / properties / living / properties / housing_mode / enum
      Previous value: -[
      -  "rent",
      -  "own"
      -]New value: +[
      +  "rent",
      +  "own",
      +  "own_outright"
      +]
  3. Changed1 schema field changed
    • addedOutput schema / properties / non_cash_deltas / items / properties / note
      Added value: +{
      +  "type": "string"
      +}
  4. Changed4 schema fields changed
    • changedOutput schema / properties / equivalence / properties / household_gross / type
      Previous value: -"number"New value: +[
      +  "number",
      +  "null"
      +]
    • addedOutput schema / properties / equivalence / properties / status
      Added value: +{
      +  "enum": [
      +    "solved",
      +    "no_solution"
      +  ],
      +  "type": "string"
      +}
    • changedOutput schema / properties / equivalence / properties / target_salary_needed / type
      Previous value: -"number"New value: +[
      +  "number",
      +  "null"
      +]
    • changedOutput schema / properties / equivalence / required
      Previous value: -[
      -  "target_salary_needed",
      -  "household_gross",
      -  "explanation"
      -]New value: +[
      +  "status",
      +  "target_salary_needed",
      +  "household_gross",
      +  "explanation"
      +]
  5. First observed

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real context beyond that: the return is a text summary plus structured JSON, and RSU income is deliberately excluded and treated as source-only. That RSU caveat is a non-obvious behavioral rule an agent could otherwise get wrong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads what the tool computes, then routing guidance, then behavioral notes. Every sentence carries weight, though the output-format sentence slightly overlaps the existing output schema and could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a nested 7-parameter schema with full description coverage and an output schema, the description supplies exactly the missing pieces: sibling routing, the RSU exclusion rule, and the dual text/JSON return shape. An agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description nonetheless adds a meaningful scope rule not in the schema: RSU is not a parameter because grants are treated as source-only. That prevents an agent from trying to model RSU as input, though it does not elaborate on the optional living/advanced/household groups beyond what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (compare) and resource (two cities for one household) and enumerates the outputs: take-home pay, cost breakdown, equivalent target salary, lifestyle deltas, and a weighted 0-100 score. It explicitly differentiates itself from get_city_summary and rank_cities, so an agent can select it without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit when-to-use (head-to-head between two named cities) and names both alternatives with the conditions that select them: get_city_summary for a single city, rank_cities for ranking many. Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.