solarbrain_analyze_contracted_power_demand
ChatGPTUse this when the user asks whether to lower or raise contracted power, or about P1/P2, maximeter, grid-demand peaks, risk, or savings. Request a wide range, but treat period.days_covered as requested calendar days only. Use historical_coverage for real observed dates and valid days, decision_readiness for recommendation versus hypothesis, and each period's recommended_kw or candidate_kw without mixing them. The basis is power demanded from the grid, not total house consumption; house_max_kw is explanatory context only.
solarbrain_assess_ev_readiness
ChatGPTUse this when the user asks whether an electric car makes sense with their current installation, how many electric kilometers exported surplus could cover, or what EV usage could fit historical surplus. If the profile is DataDis/grid_only, call it exportacion a red or excedente visible, not measured solar surplus.
solarbrain_assess_pv_battery_upgrade
ChatGPTUse this when the user asks whether it is worth adding solar panels, expanding PV, adding battery capacity, or reviewing whether the installation is well sized. Provide an explicit date range and return evidence, caveats, and next steps. For contracted-power questions use the contracted-power tool.
solarbrain_compare_energy_cohorts
ChatGPTUse this when the user asks to compare historical SolarBrain groups inside a date range, such as weekday vs weekend, month vs month, weekday patterns, or seasons. date_from and date_to are inclusive local dates. Supported group_by values are day_type, weekday, month, and season. For weather groups like sunny vs rainy, explain that weather cohorts are not yet available and use calendar cohorts or range summaries instead.
solarbrain_compare_energy_scenarios
ChatGPTRead-only VaDa Genius tool for one home-energy decision: investment path, PV size, solar/load alignment, EV fit or quote review. Select one decision_kind using quote > EV > sizing > alignment > general. Trust returned calculations, evidence labels, eligibility, ordering, blocked claims and data_sufficiency; never recreate or rerank scenarios. If the user requests a chart, set presentation=native_charts and use only returned visual_insights. quality_partial means incomplete coverage, not automatic insufficiency. Present exploratory sizing as a conditional range, never an investment promise. Answer conversationally with two or three decisive facts, the main limitation and one next step.
solarbrain_compare_tariffs
ChatGPTUse this when the user asks whether their tariff is good, expensive, worth changing, or wants better tariff alternatives using recent SolarBrain billing months. The backend compares each candidate as a continuous tariff over the whole period and includes rolling wallet balances for month-behind compensation.
solarbrain_estimate_solar_potential
ChatGPTUse this when the user asks for solar reference production, PVGIS/JRC, solar potential, expected PV generation, or a kWp scenario. It estimates European reference production for a date range and scenario. For measured-vs-reference comparisons, also use measured history tools.
solarbrain_explain_energy_anomaly
ChatGPTUse this when the user asks why something happened in their energy data, such as unusual import, export, low solar, high consumption, battery behavior, or an unexpected time slot. Use target_date and optional local times when the question is about a specific window.
solarbrain_get_active_control_state
ChatGPTUse this for Smart/EV installations when the user asks 'que hay encendido ahora', what VaDa has switched on now, which flexible loads are active, how much controlled power is running, or asks for a list/table of active devices. Use user_summary_es and active_assets for user-facing wording, locations, power, and timing fields when available; avoid technical IDs and avoid saying 'activos controlados encendidos'.
solarbrain_get_authenticated_user
ChatGPTUse this when the user asks to test Auth0, verify SSO, check which SolarBrain user is logged in, or confirm whether ChatGPT is sending an authenticated OAuth token to the MCP server. This tool requires OAuth when Auth0 is enabled.
solarbrain_get_battery_forecast
ChatGPTUse this when the user asks whether the battery will charge fully, expected state of charge, evening discharge risk, battery forecast for today, or battery evolution by hour. Prefer human, by-hour reasoning when the backend returns hourly battery data.
solarbrain_get_billing_estimate
ChatGPTUse this when the user asks for an electricity bill, invoice estimate, monthly estimation process, current month cost, last month bill, import cost, export compensation, solar savings, wallet, or bill without solar comparison. Prefer bill_story.amount_to_pay_eur as the main payable amount, and use bill_story.formula_es plus bill_story.optimization_es to explain wallet, excedentes, and the goal of zero grid import with minimal export.
solarbrain_get_billing_settings
ChatGPTUse this when the user only wants to know the current SolarBrain billing company, billing settings, tariff access, or contracted power settings. For Spanish 2.0TD, use contracted_power_context and keep P1 punta/llano separate from P2 valle; if only a single kW is visible, say that backend/MCP still lacks the split. This returns data only and does not open the editor UI.
solarbrain_get_configured_assets
ChatGPTUse this when the user asks what VaDa devices are configured, how they are named, where they are, their trigger availability, priority rules, average power, start/stop delays, or whether they are available now. This is read-only configuration; do not use it to switch devices on or off. Use display_name and location in answers, never technical IDs.
solarbrain_get_consumption_patterns
ChatGPTUse this when the user asks about historical energy patterns over a date range: hourly profile, night use, weekend vs weekday behavior, solar-window alignment, peak hours/days, or load-shifting opportunities. This is read-only pattern analysis; use contracted-power tools for P1/P2 decisions.
solarbrain_get_current_energy
ChatGPTUse this when the user asks what is happening right now with PV production, home load, grid import/export, battery state, or current energy balance, including questions such as 'como esta la bateria ahora'. This returns data only, without the house widget.
solarbrain_get_daily_operational_summary
ChatGPTUse this when the user asks about today or yesterday, including Smart device activations on that single day: how many times a device activated, when it started, how long it stayed active, and whether it appears to have started normally. It also returns solar generation, house consumption, grid import/export, battery behavior, and estimated variable cost. For recurring habits, weekday patterns, multi-day counts, trends, or charts, use solarbrain_get_energy_range_summary. Do not answer that yesterday is unavailable before calling this tool for date_preset=yesterday.
solarbrain_get_daily_outlook
ChatGPTUse this when the user asks how today is going: solar generated so far, solar now, remaining forecast, battery outlook, export/import risk, or a short daily energy briefing. This is energy-only for the authenticated installation; use device tools for configured or active VaDa automations.
solarbrain_get_energy_balance
ChatGPTUse when the user asks when PV normally exceeds home consumption, reaches equilibrium, surplus starts or ends, whether the window is stable or fragmented, about today, at least X W, or one appliance. This is the only Energy Balance tool. Set threshold_w=0 unless an explicit margin is requested. Appliance profiles are typical hypotheses; never turn historical margin into guaranteed device power or full-cycle coverage. Insufficient is a valid result. Lead with the domestic conclusion and evidence; hide units and percentiles unless asked. Use at most one returned window-and-variability visual. Mention Smart only when explicitly permitted with compatibility and authorization.
solarbrain_get_energy_price_range
ChatGPTUse this when the user asks for a complete hourly price series or graph for today, or for prices over explicit or inferable date ranges such as yesterday, today and yesterday, this month, last month, P1/P2/P3 averages, cheapest or most expensive hours in a range, or comparisons across days. date_from and date_to are inclusive local dates. This reads the published price catalog independently from household telemetry and returns at most one semantic visual_insight for short ranges. Answer only the price question unless the user asks for another energy decision.
solarbrain_get_energy_prices
ChatGPTUse this when the user asks for the current electricity price, today's cheapest or most expensive hours, tomorrow's prices, or whether to move consumption today. For a complete hourly day, a graph or visual of today's prices, yesterday, a month, a custom range, or P1/P2/P3 averages, use solarbrain_get_energy_price_range. Price data comes from the published hourly catalog independently of household telemetry. Answer only the price question unless the user also asks about battery, weather, or automation.
solarbrain_get_energy_range_summary
ChatGPTUse this for energy or Smart device activity over several days. Select it for what VaDa usually activates, weekday habits such as 'los lunes', activation counts, typical start times, durations, configured-power assessment, daily trends, or charts for the last seven days. Provide inclusive YYYY-MM-DD dates and use granularity=days for patterns or charts. Smart activity supports up to 31 days; device_activation_summary returns devices, weekday patterns, daily breakdowns, totals, and natural summaries. Longer ranges still return energy data but require a shorter period for activity. For one day use solarbrain_get_daily_operational_summary; for cohort comparisons use the cohort tool.
solarbrain_get_energy_time_window
ChatGPTUse this for measured energy in a specific local time slot or hourly window: export, import, solar, house consumption, or battery behavior between two times on a target date. Infer today only when the user clearly asks about hoy.
solarbrain_get_genius_energy_profile
ChatGPTUse this when the user asks what VaDa Genius knows about their connected energy profile or since when energy readings exist: installation, data sources, first and last observed reading, billing context, contracted power P1/P2, and capabilities. history_availability is an observed extent only; continuity is not assessed. It is read-only and focuses on energy context, not civil identity.
solarbrain_get_genius_opportunities
ChatGPTUse this when the user asks what VaDa Genius recommends next: solar, battery, EV, tariff, automation, or contracted-power opportunities. It returns read-only opportunity cards with evidence, assumptions, missing data, risks, and next actions for an explicit date range.
solarbrain_get_period_operational_summary
ChatGPTUse this when the user asks about this month, last month, monthly history, 'este mes', or 'el mes pasado'. This returns the backend semantic analytics summary: measured house consumption when DataDis import is valid as consumption, grid import/export, contract context, data-quality flags such as export_anomaly, and known missing dimensions. Prefer this over raw monthly telemetry for DataDis/grid_only installations.
solarbrain_get_solar_forecast
ChatGPTUse this when the user asks about solar generation today, tomorrow, remaining solar energy, the best solar hour, or solar production windows.
solarbrain_plan_flexible_loads
ChatGPTUse this when the user asks what to run today or tomorrow, in what order, or when to place flexible loads such as washing machine, dishwasher, dryer, oven, iron, pool, air conditioning, or a custom appliance. This is read-only advice and never switches devices. For SMART/EV installations, first separate loads already active/configured in VaDa from manual loads; do not tell the user to start something VaDa is already managing.
solarbrain_recommend_manual_load
ChatGPTUse this when the user asks whether to run a manual load now or today, such as a washing machine, dishwasher, dryer, oven, iron, or custom appliance.
solarbrain_show_live_house_snapshot
ChatGPTUse this only when the user asks for the visual house dashboard or explicitly asks about 'la casa' as a whole, for example 'muestrame la casa', 'como va la casa', or 'estado de la casa'. For direct questions about battery, solar production, grid, or what is switched on now, use the data/list tools instead.
