EnergyInCloud

Energy totals in kWh for one plant over a free date window, with an optional second window to compare (`compare_to`). Use for "how much did it produce / consume / import / export", self-consumption and autarky, "the energy flows in my house today", and any energy comparison between two periods ("this month against the same month last year"); only "everything across the board" goes to report_period. No curve (get_power_series), no euro (report_economics), no check that the numbers are right (check_energy_balance).

get_energy_summary

Send one plant's defect to the developers with the evidence attached. Use for "escalate Villa Rossi to the dev team", "this is a platform bug, open a ticket", "we tried everything, hand it over". Requires a fresh `report_ref` from diagnose_plant (no debug, no ticket), the `symptom`, every proposed action marked executed or discarded, and `user_confirmed: true`. A product that cannot do something is compose_product_request, gated by search_capabilities instead; the two refs are not interchangeable.

compose_escalation_ticket

What happened on one gateway over up to 7 days, in order: alarms, state transitions and connectivity gaps in one flat chronology. Use for "what happened over the weekend", "alarm history for the last three days", "when did it go offline and when did it come back", "what happened right before the fault"; the episode bounds from get_plant_kpis paste straight in. Capped at 7 days; `anchor` picks which end survives a dense window. Now is check_alarms; a statistical recurrence signature is check_fleet_alarms.

get_timeline

Find one of the caller's plants from a fragment: part of a name, or part of a gateway serial read off a label or a photo. Use for "find the plant with Rossi in the name", "which plant is serial ...37500002 on". Substring match, no typo tolerance; returns pointers to follow with get_plant. Never locations. A complete serial goes to get_plant directly.

search_my_plants

What firmware one plant runs, whether that is a problem, and whether an upgrade is moving on it. Use when a plant is named: "what firmware is Villa Rossi on", "is it on the latest version", "does this firmware have known bugs". `serial` or up to 20 `serials`, one row each for the whole plant, at most 50 gateways in all. `unknown` means the device is not in the firmware store: data, not an error, no retry. "Is the firmware why it's broken" is diagnose_plant; fleet questions are check_fleet_firmware (who is behind) and get_fleet_fw_rollout (how the campaign is going).

check_firmware

Are the firmware campaigns moving, and where are devices getting stuck? Fleet-wide read. Call it only when the user asks about the progress of firmware updates across the fleet. Use for "how is the rollout going", "is the campaign stuck", "how many devices failed the upgrade, and why" (`period` today/d7/d30). Counts only, no device lists; ERROR, FAILED and CANCELLED are never summed. Which devices run what is check_fleet_firmware; this device's own job is check_firmware.

get_fleet_fw_rollout

Which alarm combinations travel together across the fleet right now. Expensive: call it only when the user asks about the alarm situation across the fleet: "which alarm patterns are spreading", "is this fault tied to a firmware version", "what is alarming in installer Rossi's fleet". `family` and `installer` (UUID or name) narrow it. Pattern sets, never single codes; no geographic dimension, no history. One plant's open alarms, or whether one recurs, is check_alarms.

check_fleet_alarms

How the whole fleet is connected right now: gateways per state (online, ghost, frozen, offline) and the worst ones, one per plant, silent longest since their installation. Fleet-wide read, only on an explicit fleet ask: "how many gateways are offline", "which plants lost connection", "how is installer Rossi's fleet connected". Every installed gateway for Internal, the caller's plants otherwise; `family`, `installer` (UUID or name) and `serials` narrow it. Counts and a list, no detail: Internal drills the `worst` serials with check_connectivity, 20 per call.

check_fleet_connectivity

How complete the whole fleet's data was over a day or a week: gateways ok, degraded or mute, and the worst gateway of each plant below its family's band. Counts the days the nightly rollup has folded (yesterday and before); today is declared, not counted. Fleet-wide read, only on an explicit fleet ask: "which plants lost data this week", "how many gateways are mute". Every installed gateway for Internal, the caller's plants otherwise; `family`, `installer` (UUID or name) and `serials` narrow it. No detail: Internal drills the `worst` serials with check_data_quality, 20 per call.

check_fleet_data_quality

What firmware the fleet is actually running, one block per variant, and who is stuck behind. Fleet-wide read. Call it only when the user asks about the firmware composition of the fleet, not about pending or running upgrades. Use for "the firmware spread for 3-phase units", "how many devices are not on the latest version", "which units run version X" (`version`). `family`, `version` and `installer` (UUID or name) narrow it. One plant's firmware is check_firmware; "how is the rollout going" is get_fleet_fw_rollout.

check_fleet_firmware

Where the plant registry is broken across the whole fleet: orphans, leftovers and malformed entities, one block per anomaly class with a complete count and a capped sample of rows. Whole-registry sweep. Call it only when the user asks for a sanity check of the fleet's registry data: leftovers, malformed or orphan entries, platform errors. Fleet-wide only: one plant's registry entry is get_plant, one plant with no gateway is diagnose_commissioning. Use for "run a registry hygiene check", "plants with no owner", "anything sending data we never registered". Unscoped to any customer by design; a snapshot, so "broken since when" has no answer. Not check_settings, which checks one machine's parameters.

check_fleet_registry

A quick look at how an installed base is operating right now, and which plants to open first: connectivity, active alarms and data flow crossed per gateway and counted, the worst plants ranked. For an installer or distributor this is "how is my fleet doing"; for Internal only a shallow glance: any fleet question asked for support work (what to debug first, what is new or in fault) is report_internal_support. Fleet-wide read, only on an explicit ask about the fleet or all the plants; a question about one plant never comes here. Use for "how is my fleet doing this morning", "which of my plants are offline", "my worst ten plants" (`rank_by`). `family`, `installer` (UUID or name) and `serials` narrow it. Now only: no history, no performance. A named installer's base is report_installer_rating.

report_fleet_status

The state of one gateway right now, signal by signal: every resource and component with its decoded, named state values as the last recorded status holds them. Use for "what state is the inverter in", "is the battery charging or discharging right now", "is the backup relay engaged". No component address needed. Not a power figure: "what is it producing right now" is get_power_series. Reachability and alarms are deliberately absent: call check_connectivity and check_alarms alongside. Only Ibridi Energy has registered states; EMS Energy XL comes back empty. One component's telemetry by `component_path` is get_component_signals (both families).

get_device_status

How one installer's installed base is doing, with its rating (points, 100 the best), or the ranking of all installers, lowest score first. Fleet-scale aggregation. Call it only when the user names an installer or asks to rank installers: "how is installer Bianchi doing", "rank the installers". `installer` (UUID or name) or omit for the ranking. Aggregates only, never a plant list. The census with counts per installer is list_installers; the caller's own portfolio is report_fleet_status; who installed one plant is get_plant.

report_installer_rating

Census of installer organizations: per installer the plants it installed, their live gateways, first and last commissioning date and, with `group_by`, the plants per value of one attribute. Use for "how many plants per installer", "installers by region", "which installer is this user's" (`email`). `installer` is a UUID or a name. Counts only, no health: how well an installer's plants work is report_installer_rating.

list_installers

The plants the caller can reach, each with the name and serial of its gateways: the resolution step before any other tool. Use when nothing qualifies the ask: "list my plants", "what's my gateway serial". Paginated by `cursor`, no filters, no health. "Find the plant called ..." is search_my_plants.

list_my_plants

Tell the owner of a plant that something needs their attention, in two calls: without `send_ref` to preview the recipients and the rendered message, then with that `send_ref` to send exactly that preview. Use for "tell the owner their plant has been offline for three days", "let the customer know they need to act". One `template`, no free text, no reports: "send the customer their report" is report_period. Changing the machine is update_plant_settings (the other preview-then-confirm tool); the developers are compose_escalation_ticket or compose_product_request.

notify_plant_owner

Digest of everything that happened on a plant over a week, a month or a year: headline energies, battery, indicators, euro, alarm counts, events, data completeness, and typed highlights that carry the comparison value and delta on the energy figures. Expensive composite over every section. Call it only when the user asks for a report, a summary or period statistics of the plant; a casual question about last week or last month is not a report request and belongs to the narrow tool even when its window is capped. Use for: "prepare the monthly report", "how did the plant do last month", "what happened in September, energy, alarms, everything", "the yearly summary", "send the customer their report". Not for one subject, even over a long period: the battery ("how is the battery holding up this year") is get_battery_stats, energy comparisons get_energy_summary, uptime and efficiency get_plant_kpis, euro report_economics. Those answer in depth; this carries ten headline numbers per section, and on `period=year` battery, KPIs and euro cover the last month alone, marked partial. No verdict, no cause.

report_period

What a plant is made of: per gateway its resources and every component beneath them (type, model, serial, master flag), flattened with a `component_path` on each node; more than 8 alike childless children are counted in `leaves`, pass the parent's path as `expand` to list them. Use for "what components does it have", "how many inverters", "does it have a battery". Structure only, no values: pass a node's `component_path` unchanged to get_component_signals for its readings.

get_plant_architecture

How the machine is actually configured, read live from every gateway of the plant (the cost grows with their number), beside the registry frame and every disagreement between the two. Use for "how is Villa Rossi actually configured / set up", "what is the force-charge threshold", "we commissioned this as a PVM install, does the machine agree". Reads the device: it must be online, a DEVICE_OFFLINE is final. Read-only; EMS Energy XL not implemented. A fresh install ("does it match what I declared in the app") is check_postinstall; a plant that never worked is diagnose_commissioning; the paperwork (owner, installer, warranty) is get_plant. What changed and who changed it is check_settings; changing a value is update_plant_settings.

get_plant_configuration

What is wrong with this plant, why, and what to do about it: the rule-based diagnosis with a verdict per gateway and for the plant. Expensive: it runs the full rule engine over many upstream reads. Call it only when the user asks to diagnose, debug or verify the plant's behaviour or health because of something they observed, never for a status question, a single figure or curiosity. Use for: "debug Villa Rossi", "something is wrong, what is it", "why is it not producing", "what was going on at 3am" (`at`: the state as it was then, window `at` ± 1 h, or the `events_window_hours` ending at `at`). Returns healthy/degraded/faulty/unreachable, findings with evidence, recommended actions, and the `report_ref` that compose_escalation_ticket requires. It gathers alarms, connectivity, firmware, status, timeline and configuration itself. Not for "what's wrong right now" with no cause asked (check_alarms), "what happened before the fault" (get_timeline), "is it online" (check_connectivity), "why is the data patchy" (check_data_quality, not composed here), a named quantity (its own tool) or a period digest (report_period, no verdict). A plant that never worked is diagnose_commissioning; one that stopped working is here.

diagnose_plant

Performance indicators for one plant over a day, week or month: round-trip efficiency, data and connection uptime, time under blocking alarms, peak demand. Expensive: it aggregates a whole period. Call it when the user asks for statistics, KPIs or performance of the plant, not for a live status. Use for "give me the KPIs", "round-trip efficiency this month", "did we meet the 99 % availability" (`sla_target_pct`), "how many days had gaps in the data", and "how much peak did the battery shave": the kW figure is here, its euro value in report_economics. No alarm codes, no live reachability, no kWh totals (get_energy_summary).

get_plant_kpis

The registry card of the plant a serial belongs to: who owns, installed, distributes and warrants it, and which gateways it has. Paperwork only: not one field is read from a machine. Use for "show me the plant for this serial", "is it still under warranty", "who installed it", "which distributor", "is the registry entry for this plant complete". Not how the machine is configured: operating mode, battery limits, feed-in and metering are not in the registry.

get_plant

Did the install just finished on this gateway pass or fail? One binary verdict (pass, fail, inconclusive) over typed checks: registry, connectivity, live alarms, the commissioning log against the machine. Runs 18 checks over 3 days of evidence and reads the device: an offline gateway is a `fail`, not an error. Call it only when the subject is a newly finished installation and whether it went fine: "verify the install I just finished", "did this commissioning pass", "does the machine match what I declared in the app". Not for general information about a plant that happens to be new. Firmware is not checked; an EMS Energy XL gateway is not supported and says so. Why a commissioning failed, afterwards, is diagnose_commissioning.

check_postinstall

Power curves for one plant over a window you choose: production, consumption, grid and battery power in kW point by point, plus state of charge when `soc` is in `metrics`. Use for shapes and moments: "yesterday's power curves", "what was the SOC doing overnight", "when did the battery start discharging", and "what is the plant producing right now" (the latest points). No totals. "How much energy" is get_energy_summary; battery health is get_battery_stats.

get_power_series

Can support already do this in the product, and where exactly do they click? Italian or English. Use for "can the portal export 15-minute data", "a customer wants X, is that possible today", "is this broken or did we never build it". Returns a best_class (LIVE, BRK built but broken, API only, EXC excluded, NEW nothing), click paths, and the `capability_ref` that compose_product_request requires (issued even on no match). Manuals and alarm meanings are search_documentation: "can we do X" is here, "what does X mean" is there.

search_capabilities

Ask the developers to build or fix a product capability. Use for "open a product request for 15-minute export", "we can't do this, ask the devs to build it", "this feature is half-built, file it as a bug", "the customer insists the path you gave them doesn't work" (`disputed`, not another search). Requires a `capability_ref` from search_capabilities: run that first, and answer "does this exist" from it alone. A not_needed answer is a result, not an error. A defect on one plant is compose_escalation_ticket, gated by diagnose_plant.

compose_product_request

What this plant was worth in euro over a week, month or quarter: savings from self-consumption, export revenue, the bill with the plant against without it, the value of the peak avoided. Expensive, and the only euro tool: call it when the user asks for economic figures over a period, never for kWh. Use for "what did it save last quarter", "how much did my bill go down", "how much did I earn selling to the grid", and any question with a tariff in it (pass `tariff`; it overrides every stored figure). The current period is valued up to now; one not started yet is refused. No day, no year. No ROI, no recommendation, no what-if. kWh is get_energy_summary; the peak in kW is get_plant_kpis.

report_economics

Does one machine still hold what the installer declared at commissioning, and who changed what since? Use for "audit the settings", "does the machine match what was commissioned", "who changed the force-charge threshold, and when". `period` week/month/quarter with `date` anchors the history. Reads the device: it must be online, a DEVICE_OFFLINE is final. Ibridi Energy only. The configuration alone is get_plant_configuration; making a change is update_plant_settings; not check_fleet_registry (fleet registry rows).

check_settings

What support needs to look at across the whole fleet, in one fixed format every day, with what is new in the last 24 h: connectivity, gateways in fault and in alarm, critical patterns, firmware per variant, the silent devices. For Internal this answers every fleet question asked for support: "how is the fleet", "which plants do I debug first", "what's new since yesterday", "what is in fault right now", "which devices never sent data after being installed"; an installer's or distributor's fleet is report_fleet_status. Expensive whole-fleet composition, only on an explicit ask. Always now, no date. Never one plant: "the recap for plant X" is report_period.

report_internal_support