Domotz – Network Monitoring

Compares two configuration backup snapshots of the same device. Returns a unified diff (LCS) when both sides are <= 5000 lines; falls back to a set-based added / removed listing otherwise. When MD5s match, `diff_strategy` is `md5_match` and the summary is empty.

compare_config_backup

Create an alert rule: it fires when the named metric matches the condition (`function`) against the `operands`. Call `list_metric_functions` first for the valid functions of the metric and their operand count. The rule's `metric` is IMMUTABLE after creation: changing it requires deleting the rule via the UI and creating a new one. Then use `bind_alert_rule_to_device` to bind the rule to devices or variables.

create_alert_rule

Add a Contact to an Organization. Returns the new contact_id. Contacts belong to a single Organization.

create_contact

Creates an empty device profile in the account. A device profile bundles sensor definitions and credentials that can be applied to devices in one go. The new profile has no modules yet, so applying it changes nothing until content is added to it - report the profile as created, not as ready to apply. Returns the new `id`, which `update_device_profile`, `apply_device_profile` and `delete_device_profile` all take. Reversible via `delete_device_profile`. This tool is not idempotent: if a call fails without telling you whether the profile was created, check with `list_device_profiles` before calling again, or you will end up with two profiles of the same name.

create_device_profile

Create a new Organization for the calling account. Returns the new internal `id`. Reversible via delete_organization. Requires MCP access on the account.

create_organization

Open a temporary remote connection to one port of a device behind a collector. `rdp`, `ssh`, `telnet`, `http` and `https` return a `web_portal` URL (a browser session); `tcp` returns a `tcp_endpoint` (host, port) that answers only `public_ip`. The link is a credential: follow the response's `security_note`. Close the connection with `close_remote_connection` when it is no longer needed.

create_remote_connection

Create a new user-defined tag. `color` is cosmetic and user-visible: do not pick one yourself -- ask the user which colour they want, and omit the parameter when you cannot ask (omitted means gray). Valid values are in the `color` enum, and `update_tag` can recolour later without affecting any bindings. The new tag becomes immediately usable as a filter in search_devices / search_collectors, as an assignable id in `bind_tags`, and can be renamed or recoloured with `update_tag`. Reversible with delete_tag. For MSP accounts the tag namespace is account-wide. Requires the manage_device_tags permission; callers without it receive a permission error.

create_tag

Shows an interactive form to create a new custom tag, with a name field and a color picker. Use this tool when the user asks to create a new tag. If the user already stated the tag name or the color, pass them as the "name" and "color" arguments so they are pre-selected and the user does not have to enter them twice. Leave an argument out when the user did not mention it: the color then defaults to gray. This tool only creates a tag; it does NOT apply it to devices or collectors, and does NOT list or search existing tags.

get_create_tag_form

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. Power-cycling is supported only when `device_inventory` returns a `power_source` block for the powered device (it is on a managed PoE switch or PDU). Re-query `device_inventory` afterwards to inspect `power_source.link_freshness`.

cycle_outlet_power

Delete an alert rule. Irreversible: the rule and all its device/collector/variable bindings are removed. Idempotent: deleting a non-existent rule returns status=NOT_FOUND (no error).

delete_alert_rule

Permanently delete a Contact from an Organization. This cannot be undone.

delete_contact

PERMANENTLY delete one or more device records from a collector: the device and its history are removed entirely. This is IRREVERSIBLE - deleted devices cannot be recovered (though a device may be rediscovered later if it is still present on the network). Devices that no longer exist are reported as not-found and skipped (no error).

delete_device

Permanently deletes a device profile and everything it contains. This cannot be undone. It does NOT undo anything the profile already applied: sensors and credentials written to devices by earlier applies stay exactly as they are, so deleting a profile is not a way to roll one back. Any schedule on the profile is removed with it, so a scheduled apply stops. Check the profile with `list_device_profiles` first, so you can name what is being deleted.

delete_device_profile

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

Permanently delete an Organization. Any Collectors bound to it are unlinked (not deleted). Fails if it is the account's only Organization. This cannot be undone.

delete_organization

Delete a user-defined tag by ID. Irreversible — the tag is removed and unbound from every device and collector it was assigned to. 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 credentials stay stored. To delete the driver everywhere instead, use `delete_driver`. 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. 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

Details of one device: identity, status, capabilities, protocol coverage, attached sensors/drivers/profiles, OS, location, power source, alert configuration and end-of-life status of firmware, software and hardware. `collector_id` is the one the metric tools need. - `alerts` (managed devices): `has_shared_alerts`, `event_profile_count`, `alert_rule_count`, `alert_rule_ids`, `setup_integrations`. - `status`: ONLINE, OFFLINE (as in the Domotz app) or null for a logical device. - `power_source.available_power_actions`: what `set_device_power` accepts now (on, off, cycle, software_reboot); `power_actions_unavailable_reason` says why when it is empty. `host_device_id` + `outlet_id` are only for `cycle_outlet_power`. - `protocol`: 'ip' (own IP address), 'grouped' (several NICs of one host merged into one device, online if any of them is), 'logical' (manual placeholder with no IP, not monitored, no status). Refer to devices by name, not only by id.

device_inventory

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

Return the set of values available for filtering Domotz audit logs: the operation categories (each with its operation types), source applications, target entities, actor entities, and outcome statuses currently present in the data. Use this to discover valid arguments for `search_audit_logs` before searching.

get_audit_log_filters

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

get_collector_alert_rule_bindings

Inspect what the customer's Collector can actually run. Returns the Collector's current sandbox module version plus the full supported / unsupported `D.*` symbol lists, or, with `driver_id`, a compatibility diff for that driver 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

Credential status of every device on a collector; no secrets are returned. Per device: `has_working_credentials` (true when at least one purpose works) and its purposes (SNMP_MANAGEMENT, OS_MONITORING, CONFIGURATION_MANAGEMENT, ONVIF_CAMERA, DEVICE_MANAGEMENT), each UNLOCKED (working; AUTHENTICATED in `get_device_credentials`) or LOCKED (REQUIRED, PENDING, WRONG_CREDENTIALS or NO_AUTHENTICATION). SNMP_MANAGEMENT adds `snmp_reading_status` (CHECKING, NOT_FOUND, NOT_READING_DATA, READING_DATA). For the per-protocol detail of one device use `get_device_credentials`.

get_collector_credential_coverage

History of the collector's own metrics, as listed by `list_collector_metrics`: speed test, latency, jitter, bufferbloat, internet latency, and `uptime` (% online and downtimes). Per metric: stats (min, max and when, avg, latest, count, std, trend per second); text metrics come as `text_variables` with their distinct values. Device metrics (ping, sensors) are in `get_device_metrics`.

get_collector_metrics

Returns a single configuration backup snapshot's text for a device. 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.

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: which alert rules are active on the 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

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

The event log of one device, newest first: `timestamp`, `event` (one of the `event_type` values) and, when recorded, `details` (e.g. the IP or MAC involved). Fired alerts are in `search_alerts`; latency and packet loss of the same window in `get_device_metrics`.

get_device_history

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. When the list is truncated, `truncated: true` and `total_count` indicate that more exist.

get_device_interfaces

History and analytics of one device's metrics: its variables (sensors), its ping (latency, packet loss) and its `uptime` (% online, downtimes, and `agent_uptime`, the collector's own uptime). Per metric: stats (min, max, avg, latest, count, std, trend per second; seasonality on variables, time of the max on ping); text variables come as `text_variables` with their distinct values. The collector's own metrics (speed test, internet latency) are in `get_collector_metrics`; the device events of the same window in `get_device_history`.

get_device_metrics

List recent device-profile apply jobs: profile, author, start and end, status and failed devices (no per-device reason). Use it to check an earlier apply instead of applying again. A missing `author` means the submitter cannot be named. `hints` say what the list does not prove (running jobs, unrecorded outcomes, an empty result). Failures return an `error` field.

get_device_profile_job_history

Get how a Collector is linked to a documentation system: the linked organization, the device<->asset bindings, and whether auto-sync is on. `configured` tells whether the account has a connection to that documentation system at all; `linked` whether this collector is bound to one of its organizations. Use manage_documentation_link to link or unlink.

get_documentation_integration

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).

get_interface_traffic

Read what a collector scans, to answer why a device is not discovered. Read-only. Sections: - `discovery_settings`: `broadcast_discovery` (the subnet sweep), `scan_all_interface_ips` (OFF: only the first address of each interface defines a subnet to scan, so secondary addresses and VLAN sub-interfaces are not scanned), `dhcp_device_discovery`. - `interfaces`: `attached` subnets are scanned at layer 2 (ARP); a non-null `vlan_id` is a VLAN the collector sits on. - `routed_networks` (subnets behind a router, layer 3 only, with their `scan_probes`), `external_hosts` with `external_host_scan_policy`, `ip_scan_policy` (forced IPs and ranges), `interfaces_policy`. - `unavailable`: sections that could not be read. They come back empty: never diagnose from them (an empty `routed_networks` listed here does not mean none is configured). - `hints`: what the values mean for discovery. Read them before diagnosing. Write tools: `update_collector_settings` (the discovery flags), `manage_routed_networks`, `manage_external_hosts`, `manage_ip_scan_policy`, `set_interfaces_policy`.

get_network_configuration

Get the full details of a single Organization: name, `organization_id` (the caller-facing reference), its Contacts, and the ids of the Collectors bound to it.

get_organization