# Data tools SolarSENS MCP exposes the read-only tools below. The assistant selects a tool from your question. Every read uses the access scope of the connected account. ## Tool catalog | Tool | Title | Parameters | | ----------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_profile` | Connected Account Profile | None. | | `list_accessible_plants` | List Accessible Plants | None. | | `search_plants` | Search Plants | `query` (string, required, 1-120 characters) | | `get_plant_overview` | Get Plant Overview | `plantId` (UUID, required) | | `list_devices` | List Devices | `plantId` (UUID, required), `deviceType` (string, optional, 1-64 characters), `nameQuery` (string, optional, 1-120 characters) | | `get_plant_daily_performance` | Get Plant Daily Performance | `plantId` (UUID, required), `start` (string, required), `end` (string, required), `timezone` (string, optional) | | `query_plant_5min` | Query Plant Five-minute Values | `plantId` (UUID, required), `start` (string, required), `end` (string, required), `timezone` (string, optional), `metrics` (array of string, required) | | `query_plant_daily` | Query Plant Daily Values | `plantId` (UUID, required), `start` (string, required), `end` (string, required), `timezone` (string, optional), `metrics` (array of string, required) | | `list_alarms` | List Alarms | `plantId` (UUID, required), `status` (`active` or `cleared` or `all`, optional), `start` (string, required), `end` (string, required), `page` (integer, optional) | | `get_alarm` | Get Alarm | `plantId` (UUID, required), `alarmId` (UUID, required) | | `query_string_5min` | Query String Five-minute Values | `plantId` (UUID, required), `start` (string, required), `end` (string, required), `timezone` (string, optional), `inverterIds` (array of string, optional), `resolution` (`5min` or `15min` or `30min` or `60min`, required), `metrics` (array of string, required) | | `query_inverter_daily` | Query Inverter Daily Values | `plantId` (UUID, required), `start` (string, required), `end` (string, required), `timezone` (string, optional), `inverterIds` (array of string, optional), `metrics` (array of string, required) | | `get_plant_dashboard` | Get Plant Dashboard | `plantId` (UUID, required), `view` (`production_status` or `production_status_asset_owner` or `device_status` or `devices_detail` or `devices_simple` or `disconnected_strings`, required), `deviceType` (string, optional, 1-64 characters), `parentDeviceId` (UUID, optional), `parentDeviceType` (string, optional, 1-64 characters), `faultType` (string, optional, 1-64 characters), `page` (integer, optional), `pageSize` (integer, optional) | | `get_portfolio_dashboard` | Get Portfolio Dashboard | `view` (`site_overview` or `last_7_days_yield` or `last_7_days_yield_agg` or `devices_status_summary` or `alarm_status` or `string_health`, required), `date` (string, required), `plantIds` (array of string, optional), `alarmDays` (integer, optional) | | `get_plant_chart` | Get Plant Chart | `plantId` (UUID, required), `chart` (`power` or `power_asset_owner` or `yield` or `yield_agg` or `yield_agg_asset_owner` or `performance`, required), `date` (string, required), `resolution` (`1m` or `5m` or `15m` or `30m` or `60m`, optional) | | `query_device_telemetry` | Query Device Telemetry | `plantId` (UUID, required), `deviceId` (UUID, required), `metrics` (array of string, required), `date` (string, required), `resolution` (`1m` or `5m` or `15m` or `30m` or `60m`, optional) | | `get_string_daily_analytics` | Get String Daily Analytics | `plantId` (UUID, required), `view` (`latest` or `for_date`, required), `date` (string, optional) | No other tool is available. The tools read Plant and portfolio dashboards, day charts, device catalogs, device telemetry, string analytics, and alarms. `list_alarms` and `get_alarm` read live alarm state and alarm history for one Plant. [Tool details](#tool-details) below gives their inputs, paging, and alarm fields. If a question needs work orders, generic metric catalogs, or DataHub exports, the assistant cannot answer it through this connector today. ## `get_plant_daily_performance` parameters | Parameter | Type | Required | Notes | | ---------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `plantId` | UUID | Yes | Use the canonical Plant ID returned by discovery. | | `start` | Date or date-time (see below) | Yes | Start of the window. | | `end` | Date or date-time (see below) | Yes | Must be after `start`. | | `timezone` | IANA time zone name | No | Defaults to the Plant's own time zone. Required when the Plant record has none; the call fails with `INVALID_QUERY` otherwise. | This tool reads daily values only. It has no `interval` input. `start` and `end` accept three formats, all read in the `timezone` field: * an ISO 8601 date-time with a UTC offset, for example `2026-09-22T00:00:00+08:00`; * a date-time with no offset, for example `2026-09-22T00:00:00`; * a plain date, for example `2026-09-22`. A plain-date `start` begins at 00:00:00. A plain-date `end` covers the whole day, through 23:59:59. Example request: ``` { "plantId": "00000000-0000-0000-0000-000000000000", "start": "2026-09-01T00:00:00+07:00", "end": "2026-09-08T00:00:00+07:00", "timezone": "Asia/Ho_Chi_Minh" } ``` Each returned row carries `date`, `yieldKwh`, `performanceRatio`, `availability`, and `irradiationKwhM2`. Any of the value fields can be `null` when the source has no reading for that date; a `null` value is not the same as zero production. The demo Plant `DEMO-AI-P001` has no telemetry. A `get_plant_daily_performance` call for it returns a response with no populated rows for the requested window. Do not treat that empty result as evidence that a real Plant produced nothing; check the response coverage and warnings first. ## Response fields Every successful response can include: * a request ID; * the Plant or other entities used by the result; * the resolved date window and timezone, when the tool accepts one; * metric definitions, when relevant; and * coverage, warnings, and truncation metadata. See [Limits & errors](https://ai.solarsens.co/docs/reference/limits-and-errors.md#coverage-and-warnings) for when each value is set. Missing values remain missing. An unavailable upstream is not reported as a successful empty result. ## Shared limits * A query accepts at most 1,000 returned rows and 1 MB of serialized data. * Use the canonical Plant ID returned by discovery for later reads. A Plant name is a search input, not an authorization method. See [Limits & errors](https://ai.solarsens.co/docs/reference/limits-and-errors.md) for the full table and error codes. ## Read-only boundary The connector does not provide tools to: * read work orders; * create, edit, assign, resolve, or delete anything; * list portfolios or read management summaries, metric catalogs, or DataHub values; * control a Plant or device; * run arbitrary SQL, HTTP, storage, or backend requests; or * start export jobs. These capabilities are absent from the connector today, not merely non-mutating. Calling a tool never changes SolarSENS data. ## Tool details The docs build makes this section from the `tools/list` response of the production server. Each argument shows its JSON Schema type, whether it is required, and its constraints. A tool shows an output schema only when it advertises one. ### `get_profile` **Connected Account Profile** Return the email address for the SolarSENS account selected for this connection. Use to confirm which account is connected. Does not select or switch accounts. Read-only. Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`. Arguments: none. Output schema: ``` { "type": "object", "properties": { "email": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "required": [ "email" ], "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false } ``` ### `list_accessible_plants` **List Accessible Plants** Read the current Plant catalog for the signed-in account, all accessible Plants. Use only returned Plant IDs; never guess account scope from letters, digits, keywords, or IDs. Use for: account scope. Not for: a named Plant - use search\_plants. Next: get\_portfolio\_dashboard. Read-only. Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`. Arguments: none. ### `search_plants` **Search Plants** Read the current Plant catalog by name or code, accessible matches only. Call once with the user's name or code. If one result name equals the user's Plant name (any letter case), use it without asking. If the user gives only the end of a code, such as P043 (a full code is NORTH-P043), search the digits, such as 043; if several codes match, show all and ask. Use for: a named Plant. Not for: all Plants - use list\_accessible\_plants. Next: get\_plant\_overview. Read-only. Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`. | Argument | Type | Required | Accepted values | | -------- | ------ | -------- | ------------------- | | `query` | string | Yes | 1 to 120 characters | Input schema: ``` { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "query" ], "$schema": "https://json-schema.org/draft/2020-12/schema" } ``` ### `get_plant_overview` **Get Plant Overview** Read current identity and timezone for one accessible Plant. Use for: Plant scope and local dates. Not for: live status - use get\_plant\_dashboard. Next: get\_plant\_daily\_performance. Read-only. Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`. | Argument | Type | Required | Accepted values | | --------- | ------ | -------- | --------------- | | `plantId` | string | Yes | UUID | Input schema: ``` { "type": "object", "properties": { "plantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "plantId" ], "$schema": "https://json-schema.org/draft/2020-12/schema" } ``` ### `list_devices` **List Devices** Read the current device catalog for one Plant, all devices or one type. Use for: IDs, parents, types, and unclear names with nameQuery. nameQuery matches name or label; letter case and separators are ignored. If no device matches, call again without nameQuery to find similar names or labels. If no device or more than one device matches, stop. Show name, label, and type, and ask which device. Do not read data for all matches. Not for: offline status - use get\_plant\_dashboard. Next: query\_device\_telemetry. Read-only. Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`. | Argument | Type | Required | Accepted values | | ------------ | ------ | -------- | -------------------------------------------------------------------------------------------- | | `plantId` | string | Yes | UUID | | `deviceType` | string | No | 1 to 64 characters; matches `^[A-Za-z][A-Za-z0-9 _-]*$` | | `nameQuery` | string | No | 1 to 120 characters; Part of a device name or label. Letter case and separators are ignored. | Input schema: ``` { "type": "object", "properties": { "plantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "deviceType": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z][A-Za-z0-9 _-]*$" }, "nameQuery": { "description": "Part of a device name or label. Letter case and separators are ignored.", "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "plantId" ], "$schema": "https://json-schema.org/draft/2020-12/schema" } ``` ### `get_plant_daily_performance` **Get Plant Daily Performance** Read stored daily yield, PR, availability, and irradiation for one Plant, up to 366 days; can lag. A plain-date end (YYYY-MM-DD) includes that whole day. With offset timestamps, start is inclusive and end is exclusive. Use for: low PR and daily performance. Not for: other stored daily values - use query\_plant\_daily. Next: get\_string\_daily\_analytics. Read-only. Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`. | Argument | Type | Required | Accepted values | | ---------- | ------ | -------- | ---------------------------------------------------------------------------------------------------- | | `plantId` | string | Yes | UUID | | `start` | string | Yes | YYYY-MM-DD, or an ISO 8601 date-time with an optional UTC offset | | `end` | string | Yes | YYYY-MM-DD, or an ISO 8601 date-time with an optional UTC offset | | `timezone` | string | No | At least 1 character; IANA zone. Omit to use the Plant's timezone; required when the Plant has none. | Input schema: ``` { "type": "object", "properties": { "plantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "start": { "type": "string", "pattern": "^(?:\\d{4}-\\d{2}-\\d{2}|\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})?)$", "description": "YYYY-MM-DD, or an ISO 8601 date-time with an optional UTC offset" }, "end": { "type": "string", "pattern": "^(?:\\d{4}-\\d{2}-\\d{2}|\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})?)$", "description": "YYYY-MM-DD, or an ISO 8601 date-time with an optional UTC offset" }, "timezone": { "description": "IANA zone. Omit to use the Plant's timezone; required when the Plant has none.", "type": "string", "minLength": 1 } }, "required": [ "plantId", "start", "end" ], "$schema": "https://json-schema.org/draft/2020-12/schema" } ``` ### `query_plant_5min` **Query Plant Five-minute Values** Read stored five-minute Plant values; can lag. Up to 31 days, but 1,000 rows allow about 3 days for one metric or 1 day for 3 metrics. start inclusive, end exclusive, with offsets. Use for: numbers across days. Not for: a one-day chart - use get\_plant\_chart. Next: query\_inverter\_daily. Read-only. Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`. | Argument | Type | Required | Accepted values | | ---------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `plantId` | string | Yes | UUID | | `start` | string | Yes | ISO 8601 date-time | | `end` | string | Yes | ISO 8601 date-time | | `timezone` | string | No | At least 1 character; IANA zone. Omit to use the Plant's timezone; required when the Plant has none. | | `metrics` | array of string | Yes | 1 to 20 items; each item one of `Active Power Plant`, `Consumption Load`, `Daily irradiation`, `Daily irradiation effect`, `Daily Overspill Energy`, `Daily Overspill Energy effect`, `Daily Overspill PR`, `Daily PR`, `Daily PR Temp Corrected`, `Daily Total Energy`, `Daily Total Energy effect`, `Daily Total PR`, `Daily Yield`, `Daily Yield effect`, `Daily Yield Plant`, `Daily Yield PR`, `Daily Yield PR Temp Corrected`, `Daily Yield Total Energy`, `Daily Yield Total PR`, `Derating Power Plant`, `Five Min Overspill PR`, `Five Min PR`, `Five Min Total PR`, `Grid Power`, `Irradiance`, `Irradiation`, `Irradiation_effect`, `Overspill Energy`, `Temp-PV Module`, `Total Energy`, `Yield`, `Yield Plant`, `Yield_effect` | Input schema: ``` { "type": "object", "properties": { "plantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "start": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "end": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "timezone": { "description": "IANA zone. Omit to use the Plant's timezone; required when the Plant has none.", "type": "string", "minLength": 1 }, "metrics": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "enum": [ "Active Power Plant", "Consumption Load", "Daily irradiation", "Daily irradiation effect", "Daily Overspill Energy", "Daily Overspill Energy effect", "Daily Overspill PR", "Daily PR", "Daily PR Temp Corrected", "Daily Total Energy", "Daily Total Energy effect", "Daily Total PR", "Daily Yield", "Daily Yield effect", "Daily Yield Plant", "Daily Yield PR", "Daily Yield PR Temp Corrected", "Daily Yield Total Energy", "Daily Yield Total PR", "Derating Power Plant", "Five Min Overspill PR", "Five Min PR", "Five Min Total PR", "Grid Power", "Irradiance", "Irradiation", "Irradiation_effect", "Overspill Energy", "Temp-PV Module", "Total Energy", "Yield", "Yield Plant", "Yield_effect" ] } } }, "required": [ "plantId", "start", "end", "metrics" ], "$schema": "https://json-schema.org/draft/2020-12/schema" } ``` ### `query_plant_daily` **Query Plant Daily Values** Read stored daily Plant values, up to 366 days and 1,000 rows; can lag. start inclusive, end exclusive, with offsets. Use for: curtailment, soiling, revenue, and monthly values. Not for: yield, PR, availability, irradiation - use get\_plant\_daily\_performance. Next: query\_inverter\_daily. Read-only. Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`. | Argument | Type | Required | Accepted values | | ---------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `plantId` | string | Yes | UUID | | `start` | string | Yes | ISO 8601 date-time | | `end` | string | Yes | ISO 8601 date-time | | `timezone` | string | No | At least 1 character; IANA zone. Omit to use the Plant's timezone; required when the Plant has none. | | `metrics` | array of string | Yes | 1 to 20 items; each item one of `avg_tcell`, `daily_availability`, `daily_pr`, `daily_pr_agg`, `daily_pr_corr`, `daily_pr_corr_agg`, `daily_pr_overspill`, `daily_pr_total_agg`, `daily_pr_total_agg_corr`, `daily_rev`, `daily_s_yield`, `daily_slope_rad`, `daily_slope_rad_sensor`, `daily_total_pr`, `daily_total_pr_corr`, `daily_yield`, `daily_yield_agg`, `meter_reading`, `mthly_pr`, `mthly_pr_agg`, `mthly_pr_corr`, `mthly_pr_corr_agg`, `mthly_pr_overspill`, `mthly_pr_total`, `mthly_pr_total_agg`, `mthly_pr_total_agg_corr`, `mthly_pr_total_corr`, `mthly_slope_rad`, `mthly_slope_rad_sensor`, `mthly_yield`, `mthly_yield_agg`, `plant_curtailment`, `plant_soiling` | Input schema: ``` { "type": "object", "properties": { "plantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "start": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "end": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "timezone": { "description": "IANA zone. Omit to use the Plant's timezone; required when the Plant has none.", "type": "string", "minLength": 1 }, "metrics": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "enum": [ "avg_tcell", "daily_availability", "daily_pr", "daily_pr_agg", "daily_pr_corr", "daily_pr_corr_agg", "daily_pr_overspill", "daily_pr_total_agg", "daily_pr_total_agg_corr", "daily_rev", "daily_s_yield", "daily_slope_rad", "daily_slope_rad_sensor", "daily_total_pr", "daily_total_pr_corr", "daily_yield", "daily_yield_agg", "meter_reading", "mthly_pr", "mthly_pr_agg", "mthly_pr_corr", "mthly_pr_corr_agg", "mthly_pr_overspill", "mthly_pr_total", "mthly_pr_total_agg", "mthly_pr_total_agg_corr", "mthly_pr_total_corr", "mthly_slope_rad", "mthly_slope_rad_sensor", "mthly_yield", "mthly_yield_agg", "plant_curtailment", "plant_soiling" ] } } }, "required": [ "plantId", "start", "end", "metrics" ], "$schema": "https://json-schema.org/draft/2020-12/schema" } ``` ### `list_alarms` **List Alarms** Read live ThingsBoard alarm state for one Plant, the same list as the GUI alarm page. Ten events per page; page 0 is the first page. Start inclusive and end exclusive on creation time, with UTC offsets. Use for: active alarms and alarm history. Not for: work orders - this connector cannot read them. Next: get\_alarm for one alarm, then query\_device\_telemetry for the device curve at the alarm time. Read-only. Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`. | Argument | Type | Required | Accepted values | | --------- | ------- | -------- | ------------------------------------------------------------------------------------------------------ | | `plantId` | string | Yes | UUID | | `status` | string | No | One of `active`, `cleared`, `all`; default `active`; Alarm status. Omit to read active alarms. | | `start` | string | Yes | ISO 8601 date-time | | `end` | string | Yes | ISO 8601 date-time | | `page` | integer | No | Default `0`; 0 to 9007199254740991; Page index. 0 is the first page; omit page to read the first page. | Input schema: ``` { "type": "object", "properties": { "plantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "default": "active", "description": "Alarm status. Omit to read active alarms.", "type": "string", "enum": [ "active", "cleared", "all" ] }, "start": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "end": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "page": { "default": 0, "description": "Page index. 0 is the first page; omit page to read the first page.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "plantId", "start", "end" ], "$schema": "https://json-schema.org/draft/2020-12/schema" } ``` ### `get_alarm` **Get Alarm** Read live ThingsBoard lifecycle state for one alarm in one Plant, from the same source as the GUI alarm page. Times are epoch milliseconds. A read does not acknowledge or clear the alarm. Use for: alarm details and lifecycle times. Not for: work orders - this connector cannot read them. Next: query\_device\_telemetry for the device curve at the alarm time. Read-only. Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`. | Argument | Type | Required | Accepted values | | --------- | ------ | -------- | --------------- | | `plantId` | string | Yes | UUID | | `alarmId` | string | Yes | UUID | Input schema: ``` { "type": "object", "properties": { "plantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "alarmId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "plantId", "alarmId" ], "$schema": "https://json-schema.org/draft/2020-12/schema" } ``` ### `query_string_5min` **Query String Five-minute Values** Read stored string Idc and Udc at 5 to 60 minutes; can lag. Up to 7 days, 1,000 rows; inverterIds optional. Data is kept for about the last 72 days only. For an older date, do not call; tell the user stored five-minute string data is not kept for that date. A plain-date end (YYYY-MM-DD) includes that whole day. With offset timestamps, start is inclusive and end is exclusive. Use for: current and voltage across days. Not for: a live curve today - use query\_device\_telemetry. Next: get\_plant\_dashboard. Read-only. Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`. | Argument | Type | Required | Accepted values | | ------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------- | | `plantId` | string | Yes | UUID | | `start` | string | Yes | YYYY-MM-DD, or an ISO 8601 date-time with an optional UTC offset | | `end` | string | Yes | YYYY-MM-DD, or an ISO 8601 date-time with an optional UTC offset | | `timezone` | string | No | At least 1 character; IANA zone. Omit to use the Plant's timezone; required when the Plant has none. | | `inverterIds` | array of string | No | 1 to 50 items; each item UUID | | `resolution` | string | Yes | One of `5min`, `15min`, `30min`, `60min` | | `metrics` | array of string | Yes | 1 to 2 items; each item one of `Idc`, `Udc` | Input schema: ``` { "type": "object", "properties": { "plantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "start": { "type": "string", "pattern": "^(?:\\d{4}-\\d{2}-\\d{2}|\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})?)$", "description": "YYYY-MM-DD, or an ISO 8601 date-time with an optional UTC offset" }, "end": { "type": "string", "pattern": "^(?:\\d{4}-\\d{2}-\\d{2}|\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})?)$", "description": "YYYY-MM-DD, or an ISO 8601 date-time with an optional UTC offset" }, "timezone": { "description": "IANA zone. Omit to use the Plant's timezone; required when the Plant has none.", "type": "string", "minLength": 1 }, "inverterIds": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "resolution": { "type": "string", "enum": [ "5min", "15min", "30min", "60min" ] }, "metrics": { "minItems": 1, "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "Idc", "Udc" ] } } }, "required": [ "plantId", "start", "end", "resolution", "metrics" ], "$schema": "https://json-schema.org/draft/2020-12/schema" } ``` ### `query_inverter_daily` **Query Inverter Daily Values** Read stored inverter daily values as reported; can lag. Up to 366 days, 1,000 rows. inverterIds optional. A plain-date end (YYYY-MM-DD) includes that whole day. With offset timestamps, start is inclusive and end is exclusive. Use for: yield, availability, and losses across inverters. Not for: a live device curve today - use query\_device\_telemetry. Next: query\_string\_5min. Read-only. Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`. | Argument | Type | Required | Accepted values | | ------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `plantId` | string | Yes | UUID | | `start` | string | Yes | YYYY-MM-DD, or an ISO 8601 date-time with an optional UTC offset | | `end` | string | Yes | YYYY-MM-DD, or an ISO 8601 date-time with an optional UTC offset | | `timezone` | string | No | At least 1 character; IANA zone. Omit to use the Plant's timezone; required when the Plant has none. | | `inverterIds` | array of string | No | 1 to 50 items; each item UUID | | `metrics` | array of string | Yes | 1 to 7 items; each item one of `Daily Yield`, `availability`, `Daily Derating Loss`, `Daily Operation Time`, `unavailability_loss_kwh`, `overspill_loss_kwh`, `soiling_loss_kwh` | Input schema: ``` { "type": "object", "properties": { "plantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "start": { "type": "string", "pattern": "^(?:\\d{4}-\\d{2}-\\d{2}|\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})?)$", "description": "YYYY-MM-DD, or an ISO 8601 date-time with an optional UTC offset" }, "end": { "type": "string", "pattern": "^(?:\\d{4}-\\d{2}-\\d{2}|\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})?)$", "description": "YYYY-MM-DD, or an ISO 8601 date-time with an optional UTC offset" }, "timezone": { "description": "IANA zone. Omit to use the Plant's timezone; required when the Plant has none.", "type": "string", "minLength": 1 }, "inverterIds": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "metrics": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "Daily Yield", "availability", "Daily Derating Loss", "Daily Operation Time", "unavailability_loss_kwh", "overspill_loss_kwh", "soiling_loss_kwh" ] } } }, "required": [ "plantId", "start", "end", "metrics" ], "$schema": "https://json-schema.org/draft/2020-12/schema" } ``` ### `get_plant_dashboard` **Get Plant Dashboard** Read live and today status for one Plant and its devices. Use for: production KPIs, offline devices, and disconnected strings. Not for: past daily performance - use get\_plant\_daily\_performance. Next: list\_devices. Read-only. Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`. | Argument | Type | Required | Accepted values | | ------------------ | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `plantId` | string | Yes | UUID | | `view` | string | Yes | One of `production_status`, `production_status_asset_owner`, `device_status`, `devices_detail`, `devices_simple`, `disconnected_strings` | | `deviceType` | string | No | 1 to 64 characters; matches `^[A-Za-z][A-Za-z0-9 _-]*$` | | `parentDeviceId` | string | No | UUID | | `parentDeviceType` | string | No | 1 to 64 characters; matches `^[A-Za-z][A-Za-z0-9 _-]*$` | | `faultType` | string | No | 1 to 64 characters | | `page` | integer | No | 0 to 9007199254740991; Page index. 0 is the first page; omit page to read the first page. | | `pageSize` | integer | No | 1 to 100 | Input schema: ``` { "type": "object", "properties": { "plantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "view": { "type": "string", "enum": [ "production_status", "production_status_asset_owner", "device_status", "devices_detail", "devices_simple", "disconnected_strings" ] }, "deviceType": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z][A-Za-z0-9 _-]*$" }, "parentDeviceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "parentDeviceType": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z][A-Za-z0-9 _-]*$" }, "faultType": { "type": "string", "minLength": 1, "maxLength": 64 }, "page": { "description": "Page index. 0 is the first page; omit page to read the first page.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "plantId", "view" ], "$schema": "https://json-schema.org/draft/2020-12/schema" } ``` ### `get_portfolio_dashboard` **Get Portfolio Dashboard** Read live and today screens across accessible Plants, with 7-day yield and bounded alarm status. Pass plantIds to narrow it. Use for: Plants with problems today. Not for: one Plant over past days - use get\_plant\_daily\_performance. Next: get\_plant\_dashboard. Read-only. Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`. | Argument | Type | Required | Accepted values | | ----------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `view` | string | Yes | One of `site_overview`, `last_7_days_yield`, `last_7_days_yield_agg`, `devices_status_summary`, `alarm_status`, `string_health` | | `date` | string | Yes | YYYY-MM-DD | | `plantIds` | array of string | No | 1 to 50 items; each item UUID | | `alarmDays` | integer | No | 1 to 92 | Input schema: ``` { "type": "object", "properties": { "view": { "type": "string", "enum": [ "site_overview", "last_7_days_yield", "last_7_days_yield_agg", "devices_status_summary", "alarm_status", "string_health" ] }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD" }, "plantIds": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "alarmDays": { "type": "integer", "minimum": 1, "maximum": 92 } }, "required": [ "view", "date" ], "$schema": "https://json-schema.org/draft/2020-12/schema" } ``` ### `get_plant_chart` **Get Plant Chart** Read a Plant chart for one Plant-local day, live and today data, at 1 to 60 minutes. Use for: a one-day power, yield, or performance chart. Not for: stored numbers across days - use query\_plant\_5min. Next: query\_device\_telemetry. Read-only. Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`. | Argument | Type | Required | Accepted values | | ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------- | | `plantId` | string | Yes | UUID | | `chart` | string | Yes | One of `power`, `power_asset_owner`, `yield`, `yield_agg`, `yield_agg_asset_owner`, `performance` | | `date` | string | Yes | YYYY-MM-DD | | `resolution` | string | No | One of `1m`, `5m`, `15m`, `30m`, `60m`; default `30m` | Input schema: ``` { "type": "object", "properties": { "plantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "chart": { "type": "string", "enum": [ "power", "power_asset_owner", "yield", "yield_agg", "yield_agg_asset_owner", "performance" ] }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD" }, "resolution": { "default": "30m", "type": "string", "enum": [ "1m", "5m", "15m", "30m", "60m" ] } }, "required": [ "plantId", "chart", "date" ], "$schema": "https://json-schema.org/draft/2020-12/schema" } ``` ### `query_device_telemetry` **Query Device Telemetry** Read telemetry for one device and one Plant-local day, today or a past day, at 1 to 60 minutes. Metric keys are device telemetry names, for example Active Power. An empty series can mean a wrong key, not missing data. Get the device ID from list\_devices. Use for: device values at a time of day. Not for: string values across days - use query\_string\_5min. Next: get\_plant\_dashboard. Read-only. Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`. | Argument | Type | Required | Accepted values | | ------------ | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `plantId` | string | Yes | UUID | | `deviceId` | string | Yes | UUID | | `metrics` | array of string | Yes | 1 to 10 items; each item 1 to 64 characters; Device telemetry key names exactly as stored, for example Active Power. A wrong key returns an empty series. | | `date` | string | Yes | YYYY-MM-DD | | `resolution` | string | No | One of `1m`, `5m`, `15m`, `30m`, `60m`; default `30m` | Input schema: ``` { "type": "object", "properties": { "plantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "deviceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "metrics": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Device telemetry key names exactly as stored, for example Active Power. A wrong key returns an empty series." }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD" }, "resolution": { "default": "30m", "type": "string", "enum": [ "1m", "5m", "15m", "30m", "60m" ] } }, "required": [ "plantId", "deviceId", "metrics", "date" ], "$schema": "https://json-schema.org/draft/2020-12/schema" } ``` ### `get_string_daily_analytics` **Get String Daily Analytics** Read stored daily string analytics for one Plant, latest processed day or one past Plant-local date; can lag. Call a string weak only with the peer value it was compared with; state that value. Use for: weak strings and peer ranks. Not for: current and voltage curves - use query\_string\_5min. Next: query\_string\_5min. Read-only. Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`. | Argument | Type | Required | Accepted values | | --------- | ------ | -------- | --------------------------- | | `plantId` | string | Yes | UUID | | `view` | string | Yes | One of `latest`, `for_date` | | `date` | string | No | YYYY-MM-DD | Input schema: ``` { "type": "object", "properties": { "plantId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "view": { "type": "string", "enum": [ "latest", "for_date" ] }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "YYYY-MM-DD" } }, "required": [ "plantId", "view" ], "$schema": "https://json-schema.org/draft/2020-12/schema" } ```