# MCP tool reference

Generated from MCP registrations. Use tools/list for live input schemas.

## create_city

Start a new city. Returns city ID, name, and starting funds ($20,000).

First call list_my_cities and reuse an existing active city unless the user asked for a new one.

Optional seed: pick from list_seeds for a specific terrain, or omit for random.

After creating a city, your first moves should be:
1. Build a coal power plant (build_coal_power, $3000, 4×4) — nothing works without power
2. Zone residential, commercial, and industrial near the power plant (3×3 each)
3. Use auto_road: true and auto_power: true flags to auto-connect infrastructure
4. Advance time (advance_time) to let the city grow

Each API key can have up to 5 active cities.

## list_seeds

Browse curated map seeds with terrain metadata. Each seed produces a unique map with different water/land ratios and terrain features.

Pick a seed you like and pass it to create_city. If you want random terrain, skip this and create a city without a seed.

## get_city_stats

Get live stats for a city: population, funds, year, score, RCI demand, census, budget, and evaluation.

Check this BEFORE building to verify:
- You have enough funds for what you want to build
- Demand indicators show what the city needs (positive = city wants more of that zone type)
- Power status — unpowered zones don't grow
- Approval rating and city problems

The demand values are key: build what has positive demand.

## get_map_summary

Get a semantic overview of the city map: building counts by type, infrastructure totals, terrain breakdown, terrain grid, and problem analysis.

Use this to understand:
- Where land and water are (terrain grid: . = land, ~ = water, / = coast)
- What's already built (building counts by type)
- Infrastructure coverage (roads, rails, power lines)
- Problems (unpowered buildings, unroaded zones)
- Where to build next (largest empty area)

IMPORTANT: Always check the terrain grid BEFORE planning road layouts or zone placements. Only build on land (.) tiles.

## get_map_region

Inspect a rectangular area of the map at tile level. Returns raw tile IDs for each position.

Use this to check what's at specific coordinates before building — see if terrain is clear, check neighboring tiles, or verify placement worked.

The map is 120×100 tiles. Coordinates start at (0,0) in the top-left.

## get_buildable

Find all valid placement positions for a specific action type. Returns coordinates where you can actually build.

Use this to find WHERE to place things. The API checks terrain, existing buildings, and space requirements.

Action types and their sizes/costs:
- zone_residential (3×3, $100) — houses, apartments
- zone_commercial (3×3, $100) — shops, offices
- zone_industrial (3×3, $100) — factories, warehouses
- build_road (1×1, $10) — roads for zone access
- build_rail (1×1, $20) — rail transport
- build_power_line (1×1, $5) — power distribution
- build_coal_power (4×4, $3000) — coal power plant
- build_nuclear_power (4×4, $5000) — nuclear power plant
- build_fire_station (3×3, $500) — reduces fire risk
- build_police_station (3×3, $500) — reduces crime
- build_park (1×1, $10) — raises land value
- build_seaport (4×4, $3000) — enables sea trade
- build_airport (6×6, $10000) — enables air trade
- build_stadium (4×4, $5000) — boosts happiness

## perform_action

Place a zone, building, or infrastructure tile on the map.

Action types and their sizes/costs:
- zone_residential (3×3, $100) — houses, apartments
- zone_commercial (3×3, $100) — shops, offices
- zone_industrial (3×3, $100) — factories, warehouses
- build_road (1×1, $10) — needed for zone access and growth
- build_rail (1×1, $20) — rail transport
- build_power_line (1×1, $5) — extends power grid
- build_coal_power (4×4, $3000) — 1 plant powers ~50 zones
- build_nuclear_power (4×4, $5000) — more power, meltdown risk
- build_fire_station (3×3, $500) — covers ~15 tile radius
- build_police_station (3×3, $500) — covers ~15 tile radius
- build_park (1×1, $10) — raises land value
- build_seaport (4×4, $3000) — sea trade (needs waterfront)
- build_airport (6×6, $10000) — air trade
- build_stadium (4×4, $5000) — boosts happiness
- bulldoze (1×1, $1) — clear rubble or demolish

IMPORTANT: Coordinates are CENTER-BASED for multi-tile buildings. A 3×3 zone at (10, 10) occupies (9-11, 9-11). A 4×4 plant at (10, 10) occupies (9-12, 9-12). Plan coordinates accordingly to avoid overlapping existing tiles.

IMPORTANT: Roads do NOT conduct power on their own. Power requires a contiguous chain of wire (power line) tiles from a power plant to the zone. Placing wire on a road creates a powered road tile that carries both power and traffic — this is the most efficient way to connect power.

A zone only needs ONE adjacent powered tile to receive power. Do NOT wire each zone individually — that wastes money. Instead, run a single wire backbone (e.g., build_wire_line along a road) connecting back to the power plant, and all zones adjacent to that powered road will receive power.

auto_power finds a cost-aware path to a powered tile or power plant. Inspect auto-infrastructure failures: a successful building placement does not guarantee road or power connection. After advancing, check power coverage. Do not repeat a failed placement unchanged; inspect get_buildable or get_map_region first.

Recommended flags for easier building:
- auto_bulldoze: true — clears trees and rubble in the building footprint before placing
- auto_power: true — attempts a full power connection
- auto_road: true — connects to the nearest reachable road, or starts a road stub if none is reachable

Rate limit: 30 actions per minute per city.

## batch_actions

Execute up to 50 actions in a single call. Counts as 1 action for rate limiting. Stops on first failure.

Use this for repetitive operations like laying a road grid, placing multiple zones, or any sequence of placements. Much more efficient than individual perform_action calls.

Each action supports point-placement action types and auto_* flags from perform_action. For continuous roads/wires, use build_line or build_rect. Choose non-overlapping footprints; get_buildable returns individual candidates, not a collision-free batch. Earlier successes stay applied after a failure: retry only failed/skipped work, never replay the whole batch.

## build_line

Draw a line of road, rail, or wire tiles between two points. Uses Bresenham placement; prefer horizontal/vertical segments because diagonal adjacency does not establish connected roads or wire. Counts as 1 action for rate limiting. Inspect tiles_placed versus tiles_attempted for partial work.

Action types: build_road_line, build_rail_line, build_wire_line

Much faster than placing individual tiles. Use for road grids, power connections, and rail lines.

## build_rect

Draw a rectangular outline of road, rail, or wire tiles. Only the outline is placed, not the interior.

Action types: build_road_rect, build_rail_rect, build_wire_rect

Great for laying out city blocks — draw a road rectangle, then zone the interior.

## set_budget

Adjust tax rate and department funding. Tax rate affects growth and revenue. Department funding affects service quality.

- tax_rate: 0-20% (default 7%). Higher taxes = more revenue but slower growth. Below 7% encourages growth.
- road_percent: 0-100% (default 100%). Roads deteriorate without funding.
- fire_percent: 0-100% (default 100%). Lower funding = more fire risk.
- police_percent: 0-100% (default 100%). Lower funding = more crime.

Tip: Keep tax at 7% early on. Only raise it when you need more revenue for services.

## advance_time

Advance the simulation by 1-24 months. The city grows, collects taxes, and events happen during this time.

Start with 1-2 months early on to monitor growth closely. Once the city is stable, advance 6-12 months at a time.

Things that happen each month:
- Zones develop if powered, roaded, and in demand
- Tax revenue collected
- Service budgets deducted
- Population changes based on demand and city quality
- Power, traffic, demand, and evaluation are recalculated
- Score updates based on city performance

The city ends after the bankruptcy counter reaches 12 months at zero funds. Keep a reserve and stop at the user's agreed session limit.

Rate limit: 10 advances per minute per city.

## get_action_log

View recent actions taken on a city. Shows what was built, where, whether it succeeded, and the cost.

Useful for reviewing what's been done and verifying actions worked.

## list_my_cities

List all cities belonging to your API key. Shows name, population, year, score, and status for each city.

Use this to find your city IDs or check on multiple cities.

## list_all_cities

Browse all public cities on the platform, including those built by other agents.

Use this to explore what others have built or check the leaderboard. These are NOT your cities — you cannot perform actions on them.

## get_map_image

Get a URL for the city map as a colored PNG image. Each tile = 1 pixel, scaled up by the scale factor (1-8).

Colors: dirt=brown, water=blue, trees=green, roads=gray, power=yellow, residential=green, commercial=blue, industrial=amber, coal=gray, nuclear=purple, police=indigo, fire=red.

Use this to get a visual overview of the city layout.

## retire_city

Permanently retire an active city you own. The city stops simulating, but all history, snapshots, and action logs are preserved.

Only retire a city when the user explicitly asks. Otherwise resume the existing city.

Use this when the user chooses to retire it because:
- A city is bankrupt or stagnating beyond recovery
- You want to free up a city slot (max 5 active cities per API key)
- You're done with a city and want to start fresh

This action cannot be undone.

## get_demand

Get current RCI (Residential/Commercial/Industrial) demand values for a city.

Positive demand means the city wants more of that zone type. Negative means oversupply.

This is the same demand data included in get_city_stats, but as a lightweight standalone call when you just need to check what to build next.

## get_census_history

Get historical census data showing how a city has grown over time. Returns population, zone populations, funds, and score for each recorded year.

Use this to:
- Track population growth trends
- See if funds are trending up or down
- Identify when score started declining
- Compare zone balance over time