Domotz – Network Monitoring

Power-cycle a single outlet on a host device (PoE switch / PDU). The powered device will experience a brief outage while the outlet turns OFF and back ON. Although the outlet itself returns to its prior ON state, the device may suffer config corruption or data loss during the cycle — treat as a recovery action of last resort. The cycle is dispatched asynchronously (HTTP 202): the response confirms dispatch, not completion. Use `get_device_power_source` afterwards to inspect freshness. Source `host_device_id` and `outlet_id` from `get_device_power_source`.

cycle_outlet_power

Delete an alert rule by ID. Irreversible — the rule and all its device/collector/variable bindings are removed. Use `list_alert_rules` to discover valid IDs. Idempotent: deleting a non-existent rule returns status=NOT_FOUND (no error).

delete_alert_rule

Permanently delete a driver from the account. This is IRREVERSIBLE: the driver disappears for every device it was attached to, all existing bindings are removed, and the scheduler stops running it everywhere. Persisted metrics and configuration backups produced before deletion remain in their respective stores — only the driver definition and its bindings are removed. ALWAYS confirm with the user before calling; in particular, list the devices that currently have the driver attached so the user understands the blast radius. Use `get_driver_catalog` for the driver catalog and `list_device_drivers` per device to enumerate bindings. If the intent is just to stop running the driver on ONE device, use `detach_driver` instead.

delete_driver

Delete a user-defined tag by ID. Irreversible — the tag is removed and unbound from every device and collector it was assigned to. Use `list_tags` to discover valid IDs. Idempotent: deleting a non-existent tag returns status=NOT_FOUND (no error). Fails with `TAG_IN_USE` if the tag is still referenced by one or more custom filters; the response lists the blocking filters so the caller can edit or remove them first. Requires the manage_device_tags permission.

delete_tag

Remove the binding between a driver and a device on the given collector. The driver itself stays in the account and remains attached to other devices — only THIS device's binding is removed. The scheduler will stop running the driver on this device; any metrics already emitted are preserved. CONFIGURATION_MANAGEMENT drivers: previously persisted backups remain in storage and the device's CONFIGURATION_MANAGEMENT purpose row stays in the credential store (rotate or delete credentials via set_device_credential / UI if needed). To delete the driver everywhere instead, use `delete_driver`. Pass device_id+collector_id+driver_id; if no binding exists, the tool returns result=NOT_ATTACHED (idempotent — safe to call repeatedly).

detach_driver

Detach a preconfigured (overlay) sensor from a device. Irreversible — the overlay link is removed and the sensor stops collecting. Use `list_device_sensors` to discover the `overlay_id` for currently attached overlay sensors. Only overlay (preconfigured) sensors can be detached via MCP: TCP-port sensors and custom OID sensors must be removed via the UI in this beta. Idempotent: detaching a non-attached overlay returns status=NOT_FOUND (no error).

detach_sensor

Returns detailed information about a single device: identity, status, capabilities, protocol coverage, attached sensors/drivers/profiles, OS info, location, power source, and end-of-life (EOL) status for firmware, software, and hardware. Includes `collector_id` and `collector_name` — the numeric id (and display name) of the collector that monitors this device; needed for any subsequent metric tool call. The `power_source` section (when present) carries `host_device_id`, `outlet_id`, `outlet_type`, `link_source`, and `link_freshness`. Use `host_device_id` + `outlet_id` as the chain identifier for `cycle_outlet_power`. Use for questions about what a device is, its hardware/software, installed services, where it is, how it is powered, or whether it has reached end-of-life. When presenting results, always refer to devices by name, not just by ID.

device_inventory

Fetch device performance metrics including round-trip delay, packet loss, uptime, SNMP sensor values, and disk usage over the last 7 days. Use for questions about device health, availability, resource utilization, or network performance.

device_performance

Run an action of a driver against a device. The tool auto-selects mode based on whether the driver is attached to the device: - NOT attached → DRY-RUN. The action runs on the device (real network, real credentials) but nothing is persisted: no metric stored, no backup row created, no binding made. Use this to smoke-test newly created drivers BEFORE attach_driver. Response includes `mode: 'dry-run'`. - ATTACHED → LIVE. Standard execution against the existing binding. Results are persisted by the scheduler/backend as usual. Response includes `mode: 'live'`. The binding must have `code_is_valid: true` and `status: ENABLED`. REQUIRED authoring workflow: save_driver → set_device_credential (if needed) → execute_driver (validate) → execute_driver (get-status | backup) → confirm both outcome=success → attach_driver. The first two execute_driver calls auto-run as dry-run because no binding exists yet. After attach_driver, future execute_driver calls run live. `action_id` values: `validate`, `get-status`, `backup`, `restore`, `custom-N`. For GENERIC drivers dry-run `validate` then `get-status`; for CONFIGURATION_MANAGEMENT dry-run `validate` then `backup`. `params` is a list of {name, value} pairs; types are derived from the driver's parameter schema. `credentials` (SEPARATE top-level argument — DO NOT put inside `params`): pass `{username: str, password: str, store?: bool}` to use ad-hoc credentials for this single execution instead of (or in addition to) any credentials previously saved via `set_device_credential`. Useful in the dry-run loop to try a credential without persisting it. `store` defaults to false in dry-run, true in live mode — set explicitly to override. Passwords are redacted in audit logs. Common LLM mistake: passing credentials as an entry in `params` like `{name: 'credentials', value: {username, password}}`. That goes to the driver's parameter list and is IGNORED by the authentication path — the call then fails with INVALID_CODE/PRECONDITION because no real credentials reached the sandbox. The tool rejects this shape with WRONG_FIELD_SHAPE so you can resubmit with the top-level `credentials` arg. Logs are capped at 100 lines. DRY-RUN OUTPUT: when `mode: 'dry-run'`, the response also surfaces what the driver WOULD emit, so you can verify before attaching: `metrics` (GENERIC metric table), `variables` (legacy scalar variables), `tables`, and `backup` (CONFIGURATION_MANAGEMENT `running`/`startup`, each truncated to 4000 chars with a `*_truncated: true` flag). These keys appear only when present and only in dry-run; live runs persist results and omit them.

execute_driver

Returns identity and account context for the currently authenticated user: user ID, email, billing state, trial end date, whether the user is the account owner, and whether RBAC is enabled. For freemium users, also includes current device usage and limits. Use this as the first call to understand who you are acting as and what account capabilities are available.

get_account_info

List alert rules bound to a specific collector, including bindings at the collector level and bindings to variables owned by that collector. Use to see which alert rules are active on a collector and which metrics they target.

get_collector_alert_rule_bindings

Inspect what the customer's Collector can actually run. Without `driver_id`, returns the Collector's current sandbox module version plus the full supported / unsupported `D.*` symbol lists. With `driver_id`, returns a compatibility diff for that specific driver against this Collector, including a `compatible` flag and any `missing_features`. Use this BEFORE `attach_driver` / `execute_driver` to warn the customer when the Collector is behind on the sandbox version the driver requires — execute will otherwise fail with HTTP 412 inside execute_driver.

get_collector_capabilities

Collector-wide credential audit. Returns only credential STATUS and metadata (integration status, SNMP reading sub-status). Does NOT return passwords, private keys, or SNMP community strings. Returns every visible device on the collector (including those with `has_working_credentials: false` so missing-credential gaps are visible) along with its enabled integration purposes — SNMP_MANAGEMENT, OS_MONITORING, CONFIGURATION_MANAGEMENT, ONVIF_CAMERA, DEVICE_MANAGEMENT — and whether each purpose's credentials are working (`UNLOCKED`) or not yet validated (`LOCKED`). SNMP_MANAGEMENT integrations include `snmp_reading_status` (CHECKING / NOT_FOUND / NOT_READING_DATA / READING_DATA) when available. `has_working_credentials` is true only when at least one purpose has valid, working credentials. Status mapping to `get_device_credentials`: UNLOCKED = AUTHENTICATED; LOCKED = any of REQUIRED / PENDING / WRONG_CREDENTIALS / NO_AUTHENTICATION. For per-protocol credential drill-down on a specific device (SSH/HTTP/etc.), use `get_device_credentials`.

get_collector_credential_coverage

Returns a single configuration backup snapshot's text for a device. `config_type` selects which block to return: `running`, `startup`, or `both` (default). When running and startup configs are identical, `configs_match` is true and only the `running` block is populated for `both`. Each block carries `text` plus `line_count`, `truncated`, and `returned_lines` so the caller knows whether it was capped. `max_lines` (default 1000) caps each block independently — large enterprise configs can exceed this; raise the cap if a fuller view is needed.

get_config_backup_entry

Lists devices on a collector that have configuration backup ('config backup') enabled, with the active backup driver, mode (READ_WRITE / READ_ONLY / AVAILABLE / INSUFFICIENT_PRIVILEGE / ERROR), status (ENABLED / DISABLED), failed-inspection count, and last inspection time. Devices without a detected backup driver are simply absent — this is not an error. Driver values include CISCO_IOS, CISCO_SG30X, CISCO_CBS, LUXUL_SMBSTAX, WATCHGUARD_FIREWARE_OS, WATCHGUARD_FIREWARE_OS_TFTP, FORTIGATE, FORTIGATE_TFTP, JUN_OS, HP_ARUBA_OS, HP_ARUBA_OS_AP, HP_ARUBA_OS_CX, HP_ARUBA_OS_SWITCH, SONICWALL, MIKROTIK, NETGEAR_OS_SWITCH, DELL_OS_SWITCH.

get_config_backup_status

List alert rules bound to a specific device, including device-level bindings and bindings to variables owned by that device. Requires both collector_id and device_id. Use to see which alert rules are active on a device and which metrics they target. Call before bind_alert_rule_to_device to verify the rule is not already bound.

get_device_alert_rule_bindings

Retrieve alert and monitoring configuration status for a specific device. Returns whether shared alerts are configured, event/alert rule counts, alert rule IDs, and setup integrations. Requires a device_id.

get_device_alerts

Per-device credential status drill-down. Returns only credential STATUS and metadata (authentication status, SNMP version, public-key fingerprint, timestamps). Does NOT return passwords, private keys, or SNMP community strings. Covers SNMP version + reachability status, and per-protocol access keys (SSH / TELNET / HTTP / HTTPS / WINRM / ONVIF) with their authentication status and (where available) public-key fingerprint. Status enums — `snmp.status`: CHECKING / NOT_FOUND / NOT_READING_DATA / READING_DATA; `access_keys[].authentication_status`: AUTHENTICATED / REQUIRED / PENDING / WRONG_CREDENTIALS / NO_AUTHENTICATION. `snmp` is null when no SNMP data exists. Status mapping to `get_collector_credential_coverage`: AUTHENTICATED = UNLOCKED; any of REQUIRED / PENDING / WRONG_CREDENTIALS / NO_AUTHENTICATION = LOCKED. For collector-wide credential gap analysis, use `get_collector_credential_coverage`.

get_device_credentials

Lists the SNMP-collected interfaces on a device. Returns id as a string (= ifIndex, pass directly to `get_interface_traffic.interface_ids`), name, alias, description, admin/operational status (IF-MIB enums: up/down/testing/unknown/dormant/notPresent/lowerLayerDown), high-speed (Mbps), type (human-readable IANA ifType label, e.g. 'ethernetCsmacd', 'ieee80211', 'tunnel', 'ieee8023adLag'), and per-interface error/discard counters. Devices without SNMP credentials yield an empty result. `max_interfaces` (default 100) caps the returned list; when truncated, `truncated: true` and `total_count` indicate that more exist.

get_device_interfaces

Fetch summarised time-series analytics for one or more named metrics on a device within a time range. `metric_names` is capped at 15 per call and the total variables analysed across all metrics is capped at 30 (each metric can fan out to multiple variables, each analysed independently by the time-series analysis backend). Numeric variables are returned under `variables` with full analytics; text variables (e.g. status strings, hostnames, firmware versions) are returned under `text_variables` with `latest`, `count`, and `distinct_values` instead — they have no statistical analysis, so `include_anomalies` and `include_change_points` are ignored for them. `view=summary` (default) returns scalar stats only ({min, max, avg, latest, count, std, trend_slope, seasonality}); `view=timeseries` adds bucketed time/values arrays per variable, trimmed to `max_datapoints` (default 50). `include_anomalies` adds rolling-MAD anomaly points. `include_change_points` adds PELT segment break-points. `from`/`to` accept ISO 8601 timestamps; default window is the last 7 days (the time-series analysis backend needs a multi-day baseline for anomalies and change-points). Source `metric_names` from `list_collector_metrics` or `list_device_sensors`.

get_device_metrics

Lists the account-wide catalog of drivers available for attaching and executing on devices. Each entry returns the `id` (use as `driver_id` in `attach_driver` / `execute_driver`), `name`, `description`, `type`, `minimal_sample_period`, `last_saved_time`, and a `parameters` array describing each input (`name`, `label`, `value_type`, default `value`) — empty when the driver declares none. `code_is_valid: false` ⇒ the driver will fail at execute time and should not be attached. `credentials_required: true` ⇒ the device must have credentials configured before the driver can run; if absent, attach will fail.

get_driver_catalog

Fetch a single driver template, including its full JS code body and requirement metadata (`requirements.sandbox_version`, etc.). Use the returned `code` as the starting point for `inspect_driver` and `save_driver`.

get_driver_template

Returns traffic counters for one or more device interfaces over a time range. Octets are reported in bps (per-period delta). `interface_ids` accepts strings or integers (pass the `id` values returned by `get_device_interfaces` directly); capped at 5 per call. `view=summary` (default) returns avg/max bps and total errors/discards; `view=timeseries` adds downsampled time/values arrays per interface, capped at `max_datapoints` (default 50) and limited to in/out octets unless `include_error_series=true`. `from`/`to` accept ISO 8601 timestamps; default window is the last 24 hours.

get_interface_traffic

Returns uptime stats for a collector or device over a time range: total uptime percentage, online_seconds, total_seconds, and the list of downtime intervals. If `device_id` is omitted the response covers collector uptime; if provided, it covers device uptime (with `agent_uptime` showing how much of that range the collector itself was online). The backend caps individual queries at 31 days; obi splits longer ranges into 31-day chunks (parallel) and merges them, with an obi-side ceiling of 90 days. `from`/`to` accept ISO 8601; default window is the last 7 days.

get_uptime

Static analysis of a driver's JS against the Domotz sandbox. Two modes: pass `code`+`type` to analyze a DRAFT statelessly (nothing persisted — use this in the authoring loop while iterating), OR pass `driver_id` to inspect a SAVED driver (returns its stored `code`, code analysis, `code_is_valid`, `required_features`, and its declared `parameters`). Provide exactly one mode — not both, not neither. Returns `is_valid`, the list of analyzer errors, and a summary of which `D.*` APIs the code references. When an error points at a `D.*` symbol you don't recognize, read the per-symbol doc at MCP resource `domotz://sandbox/api/{symbol}` for signature, params, and examples (or `domotz://sandbox/api/catalog` for the full surface). Once `is_valid` is true, call `save_driver` to persist.

inspect_driver

Lists alert rule definitions in the account. Each rule defines a condition and threshold that, when matched, fires an alert. This tool returns the rule definitions (id, name, metric, function, operands, severity, attached devices/collectors). It does NOT return fired alerts — use `search_alerts` for those. Optional `entity` filter narrows to rules attached to devices (`device`) or collectors (`collector`). The `linked_entities` field shows where the rule is currently attached. `channel_ids` are not returned for existing rules — they're only available at rule creation time. Feeds `create_alert_rule` and `bind_alert_rule_to_device`.

list_alert_rules

Enumerate the metrics available on a collector — speed-test thresholds, IP-conflict status, collector uptime, security-issues counts, and the rest of the collector-scoped metric catalog. Use this to discover what can be alerted on at the collector level. Use the returned `metric` values as input to alert rule creation.

list_collector_metrics

List the user's notification channels (email, webhook, Slack, etc.). Each channel has an id, endpoint, description, and type. Use to discover channel_ids before creating an alert rule via create_alert_rule (channel_ids is a required parameter).

list_communication_channels

Lists configuration backup snapshots for a device on a collector, newest first. When `running_md5` differs from `startup_md5` the device has unsaved changes (running config diverges from what would persist across reboot). `label` is user-mutable; `source` (user / custom_driver / internal_driver) records who took the snapshot. Use `next_before` as the `before` cursor to fetch the next page. `snapshot_timestamp` is the chain identifier consumed by `get_config_backup_entry` and `compare_config_backup`.

list_config_backup_history

Lists drivers currently attached to a device. Each binding returns the driver identity, the binding status, parameter values (with secrets pre-masked), and the list of executable actions (e.g. `validate`, `get-status`, `backup`, `restore`, `custom-N`) — pass an action's `action_id` to `execute_driver`. `status: DISABLED` ⇒ the binding cannot be executed even when `code_is_valid: true`; re-enable via the UI before retrying. Empty `actions[]` ⇒ the driver is not executable.

list_device_drivers

List everything monitorable on a device. Returns the metric catalog (what CAN be alerted on — always populated, even at discovery time). Pass metric (prefix match) to also include the live variable instances for that metric, with variable_id needed for variable-level binding. When metric is omitted, only the metric catalog is returned — use this to browse what's available before drilling into a specific metric's variables. Follow up with list_metric_functions to discover valid thresholds for a metric, and list_variable_alert_rule_candidates to check whether a suitable alert rule already exists.

list_device_metrics

Lists device profiles in the account. A device profile bundles sensor definitions and credentials that can be applied to one or more devices. Use the returned `id` with `apply_device_profile`. The optional `view` parameter selects detail level: `summary` (default) returns module metadata only; `full` includes the per-module configuration JSON (~5x larger payload). Module types include SNMP_PRECONFIGURED_SENSOR, SNMP_CUSTOM_OID, TCP_SENSOR, CREDENTIAL, CUSTOM_TAG, INFO, SHARED_ALERT. `has_credentials` is true when the profile applies credentials (applying it will overwrite credentials on targeted devices).

list_device_profiles

Lists the sensors currently attached to a device, merged across CUSTOM_OID, TCP, CUSTOM_DRIVER, and PRECONFIGURED kinds. Every entry carries `kind`. CUSTOM_OID entries carry `id`, `name`, `oid`, `description`, `value_type`, `category`, `custom_name` — created via `attach_sensor(sensor_spec={kind:'custom_oid', ...})`. TCP entries carry `name`, `port`, `service`, `status`, `last_update`. CUSTOM_DRIVER entries carry `id` and `driver_name` (drivers, distinct from custom OIDs). PRECONFIGURED entries carry `id`, `name`, and `category` (overlays from `list_preconfigured_sensors`). Sibling tools: `device_inventory` for sensor counts only, `get_device_metrics` for time-series data, `list_preconfigured_sensors` for the account-wide overlay catalog.

list_device_sensors

Returns the device-type catalog used to classify devices (router, switch, AP, server, etc.). Stable across calls within an API version. Each entry has an `id` (used as the `type_id` filter in `search_devices`) and a user-facing `label`. Use to discover valid type filters before constructing a search.

list_device_types

List shared driver templates the account can start from. Each entry returns `id` (use as `template_id` in `get_driver_template` and `save_driver`), `name`, `category`, `type`, and `version`. Templates are read-only starters; creating a driver from a template still produces a new, account-owned driver.

list_driver_templates

List the evaluation functions (e.g. GREATER_THAN, LESS_THAN, RANGE, CHANGED) available for a given metric name. Each function describes the comparison used to evaluate incoming variable values. Use to discover which threshold functions can be applied when creating or describing an alert rule.

list_metric_functions

Returns the account-wide catalog of preconfigured sensors available to attach via `attach_sensor(sensor_spec={kind: 'overlay', overlay_id: ...})`. When `device_ids` is provided, each sensor includes a per-device `attached` flag indicating whether it is already attached to that device. Custom sensors (category=CUSTOM) are excluded. Sorted by `supported_device_count` descending — most-applicable first. Companion to `attach_sensor`. Distinct from `list_device_sensors` (per-device attached) and `get_device_metrics` (time-series data for a device).

list_preconfigured_sensors

Returns the account-wide catalog of user-defined tags applied to devices and collectors. Each entry includes id, name, color, and the count of devices and collectors currently using it. For MSP accounts the tag namespace is account-wide (shared across organizations). Use to discover valid tag IDs before filtering in search_devices / search_collectors or assigning tags via update_device_metadata.

list_tags

List alert rules that could be bound to a specific device variable. Each candidate includes an 'attached' flag: true means the rule is already bound to this variable, false means it could be bound. Use this right before creating a new alert rule, to reuse an existing one when possible.

list_variable_alert_rule_candidates

Returns the network topology discovered by a single collector: device-to-device links and per-outlet (port) details. `view` controls detail level — `summary` returns infrastructure-only counts (~10 nodes), `standard` (default) returns full nodes and edges, `full` adds an upstream dependency map plus the inferred root (gateway). `max_links` (default 200) caps the returned edges; when truncated, `truncated: true` and `total_links` indicate that more exist. Use to understand network structure, identify single points of failure, or trace upstream paths.

network_topology