Retrieves comprehensive environmental intelligence for a location, including Weather, Air Quality (AQI & pollutants), and Pollen (tree, grass, weed, and plant species allergen levels): current conditions, hourly forecasts/history, and daily forecasts for Weather and Air Quality; Pollen is a daily forecast only (today through +4 days, no hourly or past data).
**Available Environmental Domains & Capabilities (`capabilities`: `WEATHER`, `AIR_QUALITY`, `POLLEN` — CRITICAL):**
* **Mandatory Explicit Selection:** You **MUST** include at least one of `WEATHER`, `AIR_QUALITY`, or `POLLEN` in `capabilities` on every call. Omitting `capabilities` is **NOT allowed**.
* **Broad / Ambiguous Outdoor Queries (Full Ambient Outdoor Suite):** If the user asks a general outdoor, travel, or situational question without restricting to a specific domain (e.g., "What are outdoor conditions like right now for a run?"), **explicitly include all three capabilities** (`capabilities: ["WEATHER", "AIR_QUALITY", "POLLEN"]`) to return the complete ambient outdoor suite (Weather + Air Quality + Pollen); for a past `date`/`hour`, leave out `POLLEN`, which has no history.
* **Targeted Domain Selection (Specific Queries):** If the user asks specifically for only one or two domains (e.g., "What is the AQI in Seattle right now?"), include **only** the requested capabilities (`WEATHER`, `AIR_QUALITY`, and/or `POLLEN`). Only the requested domain(s) will be executed and returned.
**Specific Data Available by Domain:**
* **Weather (`weather`):** Temperature (Current, Feels Like, Max/Min, Heat Index), Wind (Speed, Gusts, Direction), Celestial Events (Sunrise/Sunset, Moon Phase), Precipitation (Type, Probability, Quantity/QPF), and Atmospheric Conditions (UV Index, Humidity, Cloud Cover, Thunderstorm Probability, Air Pressure).
* **Air Quality (`air_quality`):** Universal & Local Air Quality Indexes (AQI value, category, dominant pollutant), Health Recommendations across 7 sensitivity groups, and Pollutant Concentrations (`include_pollutant_concentration: true`). Each index has its own dominant pollutant; report it per index (e.g., don't give the Universal AQI's pollutant for the US AQI).
* **Pollen (`pollen`):** Daily Universal Pollen Index (UPI, 0–5) per Tree, Grass, and Weed category and per plant species (`index.value` with its `index.category`, e.g. 1 = "Very Low"), in-season status, cross-reactions, and health recommendations.
* **Missing Pollen Fields:** a missing `in_season` means not in season. Leave out plant species returned without an `index`, unless the user asks about that plant; then say no pollen data is reported for it today (don't infer a level).
**Location Rules (CRITICAL):**
The target location MUST be specified in `location` using **ONLY ONE** of the following `oneof` sub-fields:
1. **Geographic Coordinates (`lat_lng`):**
* Use when exact latitude/longitude coordinates are known.
* Example: `{"location": {"lat_lng": {"latitude": 34.0522, "longitude": -118.2437}}}`
2. **Place ID (`place_id`):**
* An unambiguous Google Maps Place ID (e.g., obtained from `search_places` or `resolve_names`).
* Example: `{"location": {"place_id": "ChIJLU7jZClu5kcR4PcOOO6p3I0"}}`
3. **Address String (`address`):**
* A city/region, neighborhood, landmark or point of interest, street address, or postal code, ideally with the city/country.
* Example: `{"location": {"address": "Paris, France"}}`
**Time & Usage Modes (`date` and `hour` — CRITICAL):**
* **Local Timezone Reference:** All `date` (`{year, month, day}`) and `hour` (`0-23`) inputs MUST be expressed in the **requested `location`'s local civil time zone** (e.g., a query for `"Paris tomorrow at 13:00"` uses `Europe/Paris` local date and hour `13`), never UTC or the caller's time zone.
* **1. Current Conditions (`date` omitted AND `hour` omitted):**
* Provide `location` and the target `capabilities` (`WEATHER`, `AIR_QUALITY`, `POLLEN`). Do **NOT** specify `date` or `hour`.
* Returns real-time Current Conditions (`CC`) for the requested domain(s) (current Weather, current-hour Air Quality, and/or today's Pollen forecast).
* For **Air Quality**, Current Conditions is a **single hour**: do **NOT** use it alone to answer air quality or broad outdoor questions about **today** as a whole (use Daily Queries below).
* **2. Hourly Forecast / History (`date` specified AND `hour` specified `0-23`):**
* Provide `location`, `date` (`{year, month, day}`), `hour` (`0-23`), and the target `capabilities`. If minutes are mentioned, round down to the nearest hour.
* **CRITICAL CONSTRAINT (`date` is REQUIRED when `hour` is set):** Providing `hour` without `date` (`date` omitted, `hour` set) is **NOT allowed** and will fail with an error. Even when the user asks about a specific hour **today** (e.g., `"at 13:00 today"`), you **MUST** populate both `date` (today's date at `location`) and `hour`.
* Executes an hourly lookup for requested Weather and/or Air Quality at `YYYY-MM-DD-HH` and a daily lookup for requested Pollen on `YYYY-MM-DD`.
* **Weather "when" questions:** for **weather** questions asking **when / what time / best time** (e.g., `"what time will it stop raining?"`), use hourly `WEATHER` calls (`date` + `hour`) for the relevant hours. A daily Weather forecast has no hourly values. For **broad outdoor** "when / best time" questions (e.g., `"when is the best time to go walking today?"`), make these hourly `WEATHER` calls in addition to the full-day call for Air Quality (and Pollen) described under Daily Queries.
* **3. Daily Queries (`date` specified AND `hour` omitted):**
* Provide `location`, `date` (`{year, month, day}` in the requested `location`'s local civil time) without `hour`, and the target `capabilities` for full-day queries (e.g., `"weather and pollen in London tomorrow"`).
* **Air Quality and broad outdoor questions about today:** for **air quality** questions and **broad outdoor** questions (which include Air Quality) about **today** (e.g., `"how will the air quality change today"`, `"is today a good day for a picnic?"`), set `date` to **today's date at `location`** (hour omitted) to get the day's hourly Air Quality series. A Current Conditions call alone returns only the current hour of Air Quality and is not enough; you may add one if the user also asks about "now".
* **Air Quality time windows:** for an air quality question about a window within one day (e.g., `"air quality between noon and 6 PM"`), prefer **one Daily call** for that date and read the window's hours from the Air Quality series, rather than sampling individual hours. If you use hourly calls, cover **every** hour of the window.
* Returns daily forecasts for requested **Weather** and/or **Pollen**, and the day's hourly **Air Quality** series covering the full local day (00:00–23:00 local): 24 historical hours for a past date, 24 forecasted hours for a future date, and for **today** the earlier hours (history), the current hour, and the remaining hours (forecast).
**Supported Time Horizons by Domain:**
* **Weather:** Hourly from 24 hours ago up to 240 hours (10 days) ahead (past hours need both `date` and `hour`); daily up to 10 days including today (today through +9 days); no daily history.
* **Air Quality:** Hourly from 720 hours (30 days) ago up to 96 hours (4 days) ahead; a full-day call must fit inside that window (in practice today −29 days through +3 days).
* **Pollen:** Daily only, today through +4 days (5 days including today); no past dates, and `hour` is ignored.
* *(Note: If several capabilities are requested and the `date`/`hour` is outside one of their ranges, the call still succeeds and returns only the supported ones.)*
* **Out-of-range requests:** If a requested date or hour may be outside a domain's supported range above (e.g., Pollen for a past date), still call `lookup_weather` for the **requested** date/hour; the error states the supported range. Do **not** call a different date, hour, or domain as a substitute.
**Domain Options & Attribution:**
* **Language (`language_code`):** Optional BCP-47 language code (e.g., `"fr"`). Defaults to `"en"`.
* **Weather Units (`weather_options.units_system` or `units_system`):** Defaults to `METRIC`. Set to `IMPERIAL` (Fahrenheit/mph) if the user implies US standards or explicitly requests Imperial units. Supported in both `weather_options.units_system` (preferred) and top-level `units_system`; if both are specified, they must not conflict.
* **Air Quality Options (`air_quality_options`):** Set `include_pollutant_concentration: true` when specific pollutant concentrations (PM2.5, PM10, O3, NO2, SO2, CO) are needed; optionally set `index_region_code` (2-letter ISO country code, e.g., `"US"`) to request a specific regional AQI scale. By default, the response includes the Universal AQI and the location's regional AQI.
* **Attribution:** Grounded output MUST be attributed to the source using the `attribution` field inside each returned domain container (`weather.attribution`, `air_quality.attribution`, `pollen.attribution`).
* **Returned Times:** Air Quality `date_time` values are already in the location's local time (`utc_offset` included); present them as-is. Weather `date_time` (current and hourly) and sunrise/sunset times are UTC; convert them to the location's local time using `time_zone`. Label all times as local.