Shows each spy's composite id (needed for spy_action), current location,
rank (Recruit/Agent/Special Agent/Senior Agent), XP, and which operations
are available at their current position.

Note: offensive missions only become available once the spy has physically
arrived in the target city. Use spy_action with action='travel' first.

Args:
    unit_id: The spy's composite ID (from get_spies output)
    action: 'travel' to move spy to a city, or a mission type to launch a mission.
        Mission types: COUNTERSPY, GAIN_SOURCES, SIPHON_FUNDS, STEAL_TECH_BOOST,
        SABOTAGE_PRODUCTION, GREAT_WORK_HEIST, RECRUIT_PARTISANS,
        NEUTRALIZE_GOVERNOR, FABRICATE_SCANDAL
    target_x: X coordinate of the target city tile
    target_y: Y coordinate of the target city tile

Travel notes:
    - Valid targets: your own cities and city-states only.
    - Allied civ cities are NOT valid travel targets.
    - Travel is queued end-of-turn; spy position updates after turn ends.

Mission notes:
    - Spy must be physically IN the target city to launch any offensive mission.
    - Use 'travel' first, then end the turn, then launch the mission.
    - COUNTERSPY defends your own city (spy must be in your city).
    - get_spies shows which ops are available at the spy's current location.

Args:
    city_id: City ID (from get_cities output)

Returns available units, buildings, and districts with production costs.
Call this when a city finishes building or to decide what to produce next.

Args:
    center_x: X coordinate of center tile
    center_y: Y coordinate of center tile
    radius: How many tiles out from center (default 2, max 4)

Args:
    unit_id: The settler's composite ID (from get_units output)

Scores locations by yields, water, defense, and resource value.
Returns top 5 candidates sorted by score.

Args:
    unit_id: The unit's composite ID (from get_units output)
    target_x: Destination X coordinate
    target_y: Destination Y coordinate

Returns estimated turns, path length, and reachable tiles this turn.

Unlike get_settle_advisor (which searches near a specific settler),
this scans all revealed land for the top 10 settle candidates.
Use this when deciding WHERE to send a settler, not just where to settle.

Scans your territory for tiles needing improvements and matches them
with idle builders. Like the builder lens in the UI — shows what to
build where and which builder is closest.

Priority tiers:
- URGENT: Pillaged improvements (yield loss), unimproved strategic resources
- HIGH: Unimproved luxury/bonus resources
- NORMAL: Empty tiles that could benefit from farms/mines/lumber mills

Call this before issuing builder orders each turn.

Shows what each civ is offering and what they want in return.
Use respond_to_trade to accept or reject.

Diplomacy encounters block turn progression. Call this if end_turn
reports the turn didn't advance. Returns any open sessions with their
dialogue text, visible buttons, and response guidance.

Shows governor points, currently appointed governors with assignments,
and governors available to appoint. Use appoint_governor to appoint one.

Args:
    governor_type: e.g. GOVERNOR_THE_EDUCATOR (Pingala), GOVERNOR_THE_DEFENDER (Victor)

Requires available governor points. Use get_governors to see options.

Args:
    governor_type: The governor type (from get_governors output)
    city_id: The city ID (from get_cities output)

Governor must already be appointed. Takes several turns to establish.

Args:
    governor_type: The governor type (from get_governors output)
    promotion_type: The promotion type (from get_governors output, shown under each governor)

Requires available governor points. Use get_governors to see available promotions.

Args:
    unit_id: The unit's composite ID (from get_units output)

Shows promotions filtered by the unit's promotion class.
Only units with enough XP will have promotions available.

Args:
    unit_id: The unit's composite ID (from get_units output)
    promotion_type: e.g. PROMOTION_BATTLECRY, PROMOTION_TORTOISE

Use get_unit_promotions first to see available options.

Shows envoy tokens available, each city-state's type (Scientific,
Industrial, etc.), how many envoys you've sent, and who is suzerain.
Use send_envoy to send an envoy.

Args:
    player_id: The city-state's player ID (from get_city_states)

Requires available envoy tokens. Use get_city_states to see options.

Shows current pantheon (if any), faith balance, and all available
pantheon beliefs with their bonuses. Use choose_pantheon to found one.

Args:
    belief_type: e.g. BELIEF_GOD_OF_THE_FORGE, BELIEF_DIVINE_SPARK

Use get_pantheon_beliefs first to see options. Requires enough faith
and no existing pantheon.

Shows whether you've founded a religion, available religion types to choose,
and beliefs grouped by class (Follower, Founder, Enhancer, Worship).
Use found_religion to found a religion after your Great Prophet activates.

Args:
    religion_type: e.g. RELIGION_HINDUISM, RELIGION_BUDDHISM, RELIGION_ISLAM
    follower_belief: e.g. BELIEF_WORK_ETHIC, BELIEF_CHORAL_MUSIC
    founder_belief: e.g. BELIEF_STEWARDSHIP, BELIEF_CHURCH_PROPERTY

Requires your Great Prophet to have already activated on a Holy Site
(via UNITOPERATION_FOUND_RELIGION). Use get_religion_beliefs
first to see available options.

Args:
    unit_id: The unit's composite ID (from get_units output)

Requires the right technology, enough gold, and the unit must have
moves remaining. The unit's movement is consumed by upgrading.

Shows era score thresholds, whether you're in a Golden/Dark/Normal age,
and lists available dedication choices with their bonuses.
Use choose_dedication to select one when required.

Args:
    dedication_index: The index of the dedication (from get_dedications output)

Use get_dedications first to see available options and their bonuses.

Args:
    other_player_id: The player ID (from get_diplomacy output)

Shows gold, resources, favor, open borders status, and alliance eligibility
for both you and the other civilization. Use before propose_trade to see
what's available.

Args:
    other_player_id: The player ID of the civilization (from get_pending_trades)
    accept: True to accept the deal, False to reject it

Use get_pending_trades first to see what's being offered.

Args:
    other_player_id: The player ID (from get_diplomacy output)
    offer_gold: Lump sum gold to give them
    offer_gold_per_turn: Gold per turn to give them (30-turn duration)
    offer_resources: Comma-separated resource types to offer, e.g. "RESOURCE_SILK,RESOURCE_TEA"
    offer_favor: Diplomatic favor to offer
    offer_open_borders: True to offer our open borders
    request_gold: Lump sum gold to request from them
    request_gold_per_turn: Gold per turn to request (30-turn duration)
    request_resources: Comma-separated resource types to request
    request_favor: Diplomatic favor to request from them
    request_open_borders: True to request their open borders
    joint_war_target: Player ID of a third civ to declare joint war against
    mode: "send" to commit the deal, "test" to preview AI's counter-offer without committing

Examples: Gift 100 gold: offer_gold=100. Trade silk for 3 gpt: offer_resources="RESOURCE_SILK", request_gold_per_turn=3.
Mutual open borders: offer_open_borders=True, request_open_borders=True.
Test a deal first: mode="test" to see what the AI thinks is fair, then mode="send" to commit.

Args:
    other_player_id: The player ID (from get_diplomacy output)

Requires being at war and past the 10-turn war cooldown.
The AI may accept or reject based on war score and relationship.

Args:
    assignments: Comma-separated slot assignments, e.g.
        "0=POLICY_AGOGE,1=POLICY_URBAN_PLANNING"
        Slots not listed keep their current policy. Use NONE to
        explicitly clear a slot (e.g. "2=NONE"). Use get_policies to
        see available policies and slot indices.

Wildcard slots can accept any policy type. Military slots accept
military policies, economic slots accept economic policies, etc.

Args:
    other_player_id: The player ID of the other civilization (from get_pending_diplomacy)
    response: "POSITIVE" (friendly) or "NEGATIVE" (dismissive)

First meetings typically have 2-3 rounds. The tool automatically detects
and closes goodbye-phase sessions (where dialogue text stops changing).
If SESSION_CONTINUES is returned, send another response for the next round.

Args:
    other_player_id: The player ID (from get_diplomacy output)
    action: One of: DIPLOMATIC_DELEGATION, DECLARE_FRIENDSHIP, DENOUNCE,
            RESIDENT_EMBASSY, OPEN_BORDERS,
            DECLARE_SURPRISE_WAR, DECLARE_FORMAL_WAR, DECLARE_HOLY_WAR,
            DECLARE_LIBERATION_WAR, DECLARE_RECONQUEST_WAR,
            DECLARE_PROTECTORATE_WAR, DECLARE_COLONIAL_WAR,
            DECLARE_TERRITORIAL_WAR

Delegations cost 25 gold and can be rejected if the civ dislikes you.
Embassies require Writing tech. Use get_diplomacy to see available actions.
Surprise war is always available if not allied/friends. Other war types
(casus belli) require specific civics and conditions.

Args:
    other_player_id: The player ID (from get_diplomacy output)
    alliance_type: One of: MILITARY, RESEARCH, CULTURAL, ECONOMIC, RELIGIOUS

Requires declared friendship and Diplomatic Service civic.
Use get_trade_options to check alliance eligibility first.

Args:
    city_id: City ID (from get_cities output)
    action: Currently supported: 'attack' (city ranged attack)
    target_x: Target X coordinate (required for attack)
    target_y: Target Y coordinate (required for attack)

For attack: city must have walls and not have fired this turn.
Range is 2 tiles from city center.

For captured/disloyal city decisions (city_id is ignored, uses pending city):
- 'keep': Keep the city (works for both captured and loyalty-flipped cities)
- 'reject': Reject/free a disloyal city (loyalty flip only)
- 'raze': Raze a captured city (military conquest only)
- 'liberate_founder': Liberate to original founder
- 'liberate_previous': Liberate to previous owner

Args:
    unit_id: The unit's composite ID (from get_units output)
    action: One of: move, attack, fortify, skip, found_city, improve, repair, remove_improvement, remove_feature, build_route, automate, heal, alert, sleep, delete, trade_route, activate, sacrifice_charges, teleport, spread_religion
    target_x: Target X coordinate (required for move/attack/trade_route/teleport)
    target_y: Target Y coordinate (required for move/attack/trade_route/teleport)
    improvement: Improvement type for builders (required for improve), e.g.
        IMPROVEMENT_FARM, IMPROVEMENT_MINE, IMPROVEMENT_QUARRY,
        IMPROVEMENT_PLANTATION, IMPROVEMENT_CAMP, IMPROVEMENT_PASTURE,
        IMPROVEMENT_FISHING_BOATS, IMPROVEMENT_LUMBER_MILL

For move/attack: provide target_x and target_y.
For trade_route: provide target_x and target_y of destination city.
For teleport: provide target_x and target_y of destination city. Traders only, must be idle (not on active route).
For improve: provide improvement name. Builder must be on the tile.
For repair: repairs a pillaged improvement on the builder's current tile. No improvement name needed.
For remove_improvement: demolishes an intact improvement on the builder's current tile (e.g. to replace a farm with a mine). Costs one charge.
For activate: activates a Great Person on their matching district.
For sacrifice_charges: Royal Society builder sacrifice — spends ALL builder charges to boost a district project (2% of cost per charge). Builder must be on the district tile.
For spread_religion: spreads religion at current tile. Missionaries/Apostles only.
For build_route: builds road/railroad on current tile. Military Engineers only. No charges used; costs 1 Iron + 1 Coal per railroad tile.
For fortify/skip/found_city/automate/heal/alert/sleep/delete: no target needed.
heal = fortify until healed (auto-wake at full HP).
alert = sleep but auto-wake when enemy enters sight range.
delete = permanently disband the unit.

Args:
    city_id: City ID (from get_cities output)
    item_type: UNIT, BUILDING, DISTRICT, or PROJECT
    item_name: e.g. UNIT_WARRIOR, BUILDING_MONUMENT, DISTRICT_CAMPUS, PROJECT_LAUNCH_EARTH_SATELLITE
    target_x: X coordinate for district/wonder placement (required for districts — use get_district_advisor to find best tile)
    target_y: Y coordinate for district/wonder placement

Tip: call get_cities first to see your cities and their IDs.

Args:
    city_id: City ID (from get_cities output)
    item_type: UNIT or BUILDING
    item_name: e.g. UNIT_WARRIOR, BUILDING_MONUMENT
    yield_type: YIELD_GOLD (default) or YIELD_FAITH

Costs gold/faith immediately. Use get_city_production to see what's available.

Args:
    tech_or_civic: The type name, e.g. TECH_POTTERY or CIVIC_CRAFTSMANSHIP
    category: "tech" or "civic" (default: tech)

Tip: call get_tech_civics first to see available options.

Make sure you've moved all units, set production, and chosen research
before ending the turn.

All 5 reflection parameters are required and must be non-empty.
These form the per-turn diary — your persistent memory across sessions:
    tactical: What happened this turn — combat, movements, improvements.
    strategic: Current standing vs rivals — yields, city count, victory path.
    tooling: Tool issues or observations. Write "No issues" if none.
    planning: Concrete actions for the next 5-10 turns.
    hypothesis: Predictions — enemy behavior, resource needs, timelines.

IMPORTANT: Reflections are recorded BEFORE the AI processes its turn.
Anything that surfaces after end_turn (diplomacy proposals, AI movements,
events reported in the turn result) belongs in the NEXT turn's diary.
If end_turn is blocked and you call it again after resolving the blocker,
the diary entry from the first call is kept — do not repeat reflections.

Args:
    last_n: Number of most recent entries to return (default 5, max 50).
            Used when turn/from_turn/to_turn are not specified.
    turn: Return the single entry for this turn number.
    from_turn: Return entries from this turn onward (inclusive).
    to_turn: Return entries up to this turn (inclusive).

Auto-detects the current game from the live connection. Each game has
its own diary file (keyed by civ + random seed).

Call this at the start of a session or after context compaction to
restore strategic memory from previous turns.

Args:
    unit_id: The trader's composite ID (from get_units output)

Shows domestic and international destinations. Use unit_action
with action='trade_route' and target_x/target_y to start a route.

Args:
    city_id: City ID (from get_cities)
    district_type: e.g. DISTRICT_CAMPUS, DISTRICT_HOLY_SITE, DISTRICT_INDUSTRIAL_ZONE

Returns valid placement tiles ranked by adjacency bonus.
Use set_city_production with target_x/target_y to build the district.

Args:
    city_id: City ID (from get_cities output)
    wonder_name: Wonder building type, e.g. BUILDING_CHICHEN_ITZA, BUILDING_ORSZAGHAZ

Returns valid placement tiles ranked by displacement cost (lowest = best):
tiles with no improvements or resources are preferred over productive tiles.
Also shows terrain, feature, river/coastal status, and any resources/improvements
that would be removed by placing the wonder there.
Use set_city_production with target_x/target_y to build the wonder.

Args:
    city_id: City ID (from get_cities)

Shows cost, terrain, and resources for each purchasable tile.
Tiles with luxury/strategic resources are listed first.

Args:
    city_id: City ID
    x: Tile X coordinate
    y: Tile Y coordinate

Use get_purchasable_tiles first to see costs and options.

Args:
    government_type: e.g. GOVERNMENT_CLASSICAL_REPUBLIC, GOVERNMENT_OLIGARCHY

Use get_policies to see current government. First switch after
unlocking a new tier is free (no anarchy).

Args:
    unit_index: The Great Person unit's index (from get_units output).

Lists all cities with the matching district (e.g., campuses for Great Scientists),
showing which ones the GP can activate on, distance, city yield, and great work
slot availability for cultural GPs.

Args:
    individual_id: The individual's ID (from get_great_people output, shown after ability)

Requires enough Great Person points for that class.
The GP spawns in your capital. Use get_great_people to check [CAN RECRUIT] status.

Args:
    individual_id: The individual's ID (from get_great_people output)
    yield_type: YIELD_GOLD (default) or YIELD_FAITH

Costs shown in get_great_people output under "Patronize:".
Requires enough gold/faith to cover the cost.

Args:
    individual_id: The individual's ID (from get_great_people output)

Costs faith. The next Great Person in that class becomes available.
Use when you don't want the current GP and want to save points for a better one.

Shows whether congress is in session, resolutions to vote on (with options A/B
and possible targets), turns until next session, and your diplomatic favor.
When in session, use queue_wc_votes to register votes before end_turn.

Args:
    votes: JSON array of vote objects, e.g.
        '[{"hash": -513644209, "option": 1, "target": 2, "votes": 5}]'
        hash = resolution type hash (from get_world_congress)
        option = 1 for A, 2 for B
        target = player ID for PlayerType resolutions (from get_world_congress
                 target list, e.g. [target=2] Portugal), or target value for
                 non-player resolutions. The handler resolves to the correct
                 0-based index at runtime.
        votes = max votes to allocate (will use as many as favor allows)

Call this BEFORE end_turn when get_world_congress shows 0 turns until next
session. Registers an event handler that fires during WC processing and
casts your votes with the specified preferences.

If you don't call this, end_turn will pause at the World Congress session
and return control to you for interactive voting.

Args:
    city_id: City ID
    focus: One of: food, production, gold, science, culture, faith, default
           'default' clears all focus settings.

Cities automatically assign citizens to tiles. This biases the AI
toward the chosen yield type when assigning new citizens.

Args:
    code: Lua code to execute. Use print() for output, end with print("---END---").
    context: "gamecore" (default) for read-only state queries.
             "ingame" for commands and UI-dependent queries.

Context differences:
  gamecore: Players[], GameInfo.*, Map.*, Game.* — safe read-only access.
            CANNOT use: UI.*, UnitManager.*, CityManager.*, notifications.
  ingame:   All APIs including UI.*, UnitManager.*, CityManager.*.
            Use for: moving units, setting research, diplomacy actions.

Always use print() for output (not return).

Returns indexed list of saves. Use load_save(save_index=N) to load one.
Call this before load_save to see what's available.

Args:
    save_index: Index number from list_saves output (1-based)

The game will reload entirely. Wait ~10 seconds after calling this,
then use get_game_overview to verify the loaded state.

Args:
    save_name: Save name without extension (e.g. "0_MCP_0079",
               "0A_GROUND_CONTROL", "AutoSave_0221", "quicksave").

Tries Lua-based loading first (fast, ~5s). If the save isn't found
via Lua (common for autosaves/quicksaves), falls back to OCR menu
navigation (~90s) after verifying the file exists on disk.

Only kills Civ 6 processes. Waits ~10 seconds for Steam to deregister
so the game can be relaunched cleanly.

Starts the game and waits for the process to appear (~15-30 seconds).
The game will be at the main menu after launch — use load_save or
restart_and_load to load a specific save.

NOTE: FireTuner connection is NOT available at the main menu.
Only in-game MCP tools work after a save is loaded.

Args:
    save_name: Autosave name (e.g. "AutoSave_0221"). If not provided,
               loads the most recent autosave.

Requires the game to be running and at the main menu. Uses macOS Vision
OCR to find and click menu elements. Takes 30-90 seconds.

After loading, wait ~10 seconds then call get_game_overview to verify.

Requires pyobjc: uv pip install 'civ6-mcp[launcher]'

Args:
    save_name: Autosave name (e.g. "AutoSave_0221"). If not provided,
               loads the most recent autosave.

This is the recommended tool for recovering from game hangs (e.g. AI turn
processing stuck in infinite loop). Takes 60-120 seconds total:
1. Kills the game process
2. Waits for Steam to deregister (~10s)
3. Relaunches via Steam (~15-30s for process start + main menu)
4. Navigates menus via OCR to load the save (~30-60s)

After completion, wait ~10 seconds then call get_game_overview to verify.