Flight Sim Search Skill

❌ DO NOT TRIGGER — Real-world travel planning

The user wants to book or plan personal travel. Signals include:

• Destination + date: "flights to Amsterdam in early June", "fly to Tokyo next week"
• Price/booking language: "cheapest flight to London", "book me a ticket"
• Personal travel context: "I'm planning a trip to...", "vacation flights to..."
• Seat/class preferences: "business class to Dubai", "direct flights under $500"
• No aircraft type or sim context: just destinations and dates without sim indicators

If in doubt, look for aircraft type codes or sim terminology — their presence almost always means flight sim discovery.

Core Principles

1. Maximize options — When a user asks for flights, default to providing many results (50–60 in compact mode) unless they ask for fewer. Offer related alternatives (similar routes, alternate aircraft, nearby durations).

2. Smart response sizing — Match the response mode to the result count:

   Results	Mode	Key settings
   1–50	Standard + URLs	includeUrls: true
   50–100	Standard, no URLs	defaults
   100–200	Standard, no URLs	compact: false
   200+	Compact	compact: true (URLs unavailable)

3. URLs are OFF by default — Only include them when the user explicitly asks for links or the result set is small (< 50). Prefer SimBrief and FR24 links when included.

4. Categorize for clarity — Group results by airline, route/region, aircraft type, duration range, or time of day when it improves readability.

Search Tool Quick Reference

searchFlights — Primary tool

Supporting tools

• getFlightByIdentifier — Look up a specific flight (e.g. "LH765").
• getFlightByDatabaseId — Look up by database ID.
• listAircraftTypes — List all aircraft in the database.
• queryDatabase — Run read-only SQL for complex queries.

MSFS 2024 Addon tools

• listMSFSAddons — Browse/filter addons (type, developer, installed status, etc.).
• createMSFSAddon / updateMSFSAddon / deleteMSFSAddon / getMSFSAddon — CRUD for addon entries.

SimBrief & Weather tools

• getLatestFlightPlan / getDispatchBriefing — Retrieve SimBrief flight plans.
• getNotams — NOTAMs for flight plan airports.
• getAviationWeather — Current METAR observations.
• getVatsimAtis — VATSIM ATIS information.

Search Strategy

Single aircraft type, single duration

Straightforward — one searchFlights call:

searchFlights(aircraftType: "A359", durationMinutes: 480, limit: 200, compact: true)

Multiple aircraft types (e.g. "A359 or A35K")

Run separate searches per aircraft type and combine results:

searchFlights(aircraftType: "A359", durationMinutes: 480, limit: 200, compact: true)
searchFlights(aircraftType: "A35K", durationMinutes: 480, limit: 200, compact: true)

Present results grouped by aircraft type with clear section headers.

Open-ended exploration ("find me a cool long-haul")

Use broader parameters and curate the results:

• Search with just minDurationMinutes: 480 and a high limit
• Group results by airline or region for browsability
• Highlight unique or scenic routes

Presenting Results

Use markdown tables. The standard columns are:

| Flight | Aircraft | Route (ICAO) | Duration | Departure (Local) | Arrival (Local) |

Add a | Links | column only when URLs are included.

Formatting details:

• Duration as HH:MM (e.g. 09:30)
• Times with timezone abbreviation (e.g. 03:27 AM IST)
• Route as ORIG → DEST
• Group by airline/category with ### headers and --- separators
• Include flight count in each section header

Multi-airline queries

Group each airline under its own header:

### Lufthansa (DLH) — 25 Flights
| ... |
---
### Turkish Airlines (THY) — 22 Flights
| ... |

Duration-based queries

Consider grouping by range (short-haul < 3 h, medium 3–6 h, long 6–9 h, ultra 9+ h).

Duration Conversion

Always convert user-friendly hours to minutes for the API:

• "around 9 hours" → durationMinutes: 540
• "9–9.5 hours" → minDurationMinutes: 540, maxDurationMinutes: 570
• "under 3 hours" → maxDurationMinutes: 180
• "over 12 hours" → minDurationMinutes: 720
• "8hr flights" → durationMinutes: 480
• "at least 6 hours" → minDurationMinutes: 360

Common Airline ICAO Codes

Lufthansa: DLH · Turkish: THY · Singapore: SIA · Delta: DAL · Iberia: IBE · Ethiopian: ETH · China Airlines: CAL · Cathay Pacific: CPA · American: AAL · United: UAL · British Airways: BAW · Emirates: UAE · Qatar: QTR · Air France: AFR · KLM: KLM

URL Construction

See references/url-construction.md for full templates and field mappings.

Quick reference:

When URLs weren't fetched from the server (compact mode or large results), construct them manually from the flight data fields you already have.

Compact Mode Field Mapping

Standard → Compact: flightnumber → flt, aircrafttype → acft, departureicaocode → orig, arrivalicaocode → dest, flightdurationmins → durMins, departuretimelocal → depLocal, arrivaltimelocal → arrLocal.

Helpful Follow-ups

End responses with a relevant suggestion:

• "Would you like SimBrief dispatch links for any of these?"
• "Want to explore different aircraft on this route?"
• "Should I narrow these down by time of day or specific airports?"

Error Handling

If a search returns few or no results:

1. Suggest broadening criteria (wider duration, remove aircraft filter).
2. Verify ICAO codes are correct.
3. Offer to search similar routes or airlines.
4. Use listAircraftTypes to confirm aircraft availability.

Advanced: Custom SQL

For complex queries the standard search can't handle, use queryDatabase:

SELECT * FROM flightawareflightdata
WHERE airline = 'DLH'
  AND aircrafttype = 'A359'
  AND flightdurationmins BETWEEN 540 AND 570
ORDER BY departuretimelocal
LIMIT 30;