This tool queries GET /api/account/info via `AccountApi.get_account_info()` to get
details about the account currently linked to the Busy Bar unit.

Returns an AccountInfo object containing:
    - linked (bool): Whether the device is linked to a busy bar account
    - id (str): The unique account identifier (UUID)
    - email (str): The email address associated with the account
    - user_id (str): The user identifier (UUID)

Use case:
    Verify an account is properly linked and inspect the associated email before
    performing account-specific operations like displaying messages or notifications.

This tool queries GET /api/account/status via `AccountApi.get_account_status()` to
learn whether the device's MQTT client is actively connected to the busy bar server.

Returns an AccountStatus object containing:
    - status (str): Connection state, one of "connected", "disconnected", or "error"

Use case:
    Check MQTT connectivity before pushing data that requires cloud sync; if the
    account is not connected, queue operations locally until reconnection.

This tool queries GET /api/account/backend via `AccountApi.get_account_backend()` to
inspect how the device is configured to reach the busy bar server over MQTT.

Returns an AccountBackend object containing:
    - server_url (str): MQTT server URL to connect to (e.g., "default", "mqtts://mqtt.example.com:8883")
    - client_cert_type (str): Client certificate type, one of "default", "custom", or "none"
    - ignore_server_cert (bool): Whether to ignore the server certificate during TLS handshake

Use case:
    Inspect backend configuration during MQTT troubleshooting; confirm the server URL
    and certificate settings match expectations.

This tool queries GET /api/busy/snapshot via `BusyApi.get_busy_snapshot()` to
return the current BUSY timer state including active profile and timing details.

Returns a BusySnapshot object containing:
    - snapshot (BusySnapshotSnapshot): The busy snapshot data — varies by type:
        - BusySnapshotSimple: started (bool), remaining_ms (int)
        - BusySnapshotInterval: started, remaining_ms, interval_index, intervals_count
        - BusySnapshotInfinite: started (bool)
        - BusySnapshotNotStarted: fields not applicable
    - snapshot_timestamp_ms (int): Timestamp of the snapshot in milliseconds since epoch

Use case:
    Check what BUSY timer profile is currently active and how much time remains
    before scheduling display messages or other operations around the timer.

This tool queries GET /api/ble/status via `BLEApi.get_ble_status()` to return
the current Bluetooth Low Energy module state.

Returns a BleStatusResponse object containing:
    - status (str): Current BLE status string (e.g., "powered_on", "powered_off")
    - address (str | null): BLE MAC address if available

Use case:
    Verify the BLE module is powered on and has a valid address before attempting
    Bluetooth operations like smart home pairing or device discovery.

This tool queries GET /api/access via `SettingsApi.get_http_access()` to obtain
the current HTTP API key management mode and validity state.

Returns an HttpAccessInfo object containing:
    - mode (str): HTTP access mode — one of "default", "custom_key", or "disabled"
    - key_valid (bool): Whether the configured key is currently valid

Use case:
    Inspect HTTP access configuration before deploying tools that rely on the device's
    HTTP API (e.g., remote messaging) to confirm the key setup is correct.

This tool queries GET /api/name via `SettingsApi.get_name()` to obtain
the human-readable name currently set for this unit.

Returns a NameInfo object containing:
    - name (str): The device name (e.g., "My Busy Bar")

Use case:
    Confirm or audit the display name shown on the device, especially useful in
    multi-device setups where each unit needs an identifiable label.

This tool queries GET /api/display/brightness via `SettingsApi.get_display_brightness()`
to obtain the current screen brightness level.

Returns a DisplayBrightnessInfo object containing:
    - value (int): Brightness level as an integer percentage or stepped value

Use case:
    Check brightness before adjusting display behavior, or audit settings during
    device configuration management.

This tool queries GET /api/audio/volume via `SettingsApi.get_audio_volume()`
to obtain the current volume level configuration.

Returns an AudioVolumeInfo object containing:
    - volume (int): Volume level as an integer value

Use case:
    Check or audit volume settings before playing audio notifications or tones;
    useful for confirming device is configured at an audible level.

This tool queries GET /api/smart_home/pairing via `SmartHomeApi.get_smart_home_commissioning_status()`
to learn how many Matter fabric entries exist and the latest pairing outcome.

Returns a SmartHomePairingInfo object containing:
    - fabric_count (int): Number of commissioned Matter fabrics
    - latest_pairing_status (str | null): Status of the most recent pairing attempt
        (e.g., "success", "failure", or null if no attempt yet)

Use case:
    Verify smart home device commissioning state before troubleshooting connectivity,
    confirming pairings, or starting a new setup flow.

This tool queries GET /api/smart_home/switch via `SmartHomeApi.get_smart_home_switch_state()`
to read the current relay/driver output configuration.

Returns a SmartHomeSwitchState object containing:
    - state (str): Current switch/output state (e.g., "on", "off")
    - startup (str | null): Startup behavior — what the switch does on power-on
        (e.g., "restore", "on", "off", "unknown")

Use case:
    Check whether a smart home relay is currently active or inspect its configured
    startup behavior to avoid unexpected device activation after power events.

This tool calls `StorageApi.list_storage_files(path)` to enumerate the directory
contents on the device's internal storage for the specified path.

Args:
    path: The directory path to list (e.g., "/", "/photos"). Defaults to "/".

Returns a StorageList object containing:
    - A list of StorageListElement objects, each with:
        - type (str): File type — "file" or "dir"
        - name (str): Name of the file or directory

Use case:
    Browse device storage to find files before uploading, downloading, or managing
    media assets for display on the Busy Bar unit.

This tool queries GET /api/storage/status via `StorageApi.get_storage_status()`
to learn current flash storage usage and available space.

Returns a StorageStatus object containing:
    - used_bytes (int): Bytes currently used on the device storage
    - free_bytes (int): Bytes available for writing
    - total_bytes (int): Total capacity of the storage

Use case:
    Check available storage before uploading files or media to confirm there is
    sufficient space, and monitor storage consumption over time.

This tool queries /api/version on the device to learn which set of API
operations are available.  Returns the full version response including
api_semver and any other metadata the device exposes.

Returns a VersionInfo object containing:
    - api_semver (str): API SemVer string (e.g., "0.0.0")

Use case:
    Call this first when building integrations to verify API compatibility
    with the connected Busy Bar unit before issuing further commands.

This tool queries /api/transport on the device.  The returned information
describes how the MCP server is communicating with the Busy Bar hardware —
typically "usb" (USB ethernet) or "wifi" (Wi-Fi).

Use case:
    Diagnose connectivity path issues; shows whether the device is reachable
    via USB network interface or a Wi-Fi connection.

This tool queries GET /api/status via `SystemApi.get_status()` and returns a comprehensive
overview of whether the device is online and healthy.  The response bundles four sub-objects:
device, firmware, system, and power.

Returns a Status object containing:
    - device (StatusDevice): Hardware identifiers — serial_number, usb_mac, wifi_mac,
      ble_mac, otp_valid, otp_model, otp_timestamp, firmware_security
    - firmware (StatusFirmware): Firmware details — version, target, branch, build_date,
      commit_hash, intercom_version, nwp_version, matter_version
    - system (StatusSystem): System metrics — api_semver, uptime, boot_time, auto_update_enabled
    - power (StatusPower): Power state — state (discharging/charging/charged), battery_charge
      (int %), battery_voltage (mV), battery_current (mA), usb_voltage (mV)

Use case:
    A quick health-check to confirm the device is reachable and in a valid
    operational state before issuing other commands.

This tool queries GET /api/status/device via `SystemApi.get_status_device()` to obtain
physical identifiers and manufacturing details of the unit.

Returns a StatusDevice object containing:
    - serial_number (str): Device serial number
    - usb_mac (str): MAC address of the USB ethernet interface
    - wifi_mac (str): Wi-Fi MAC address
    - ble_mac (str): Bluetooth Low Energy MAC address
    - otp_valid (bool): Whether OTP data has been programmed and is valid
    - otp_model (str): Device model code (e.g., "BB.1")
    - otp_timestamp (int): Production timestamp as Unix epoch seconds
    - firmware_security (str): Firmware signature protection state — one of "secure",
      "insecure", "other", or "unknown"

Use case:
    Inventory tracking, device identification in multi-device setups, or
    troubleshooting hardware-specific issues.

This tool queries GET /api/status/firmware via `SystemApi.get_status_firmware()` to get
information about the firmware currently installed on the unit.

Returns a StatusFirmware object containing:
    - version (str): Firmware version string (e.g., "1.0.0")
    - target (int): Firmware target code
    - branch (str): Git branch name the firmware was built from
    - build_date (str): Build date (e.g., "2024-01-01")
    - commit_hash (str): Git commit hash, may include a "-dirty" suffix
    - intercom_version (str): Intercom handshake version string
    - nwp_version (str): Radio firmware / NWP version (e.g., "1711.2.14.5.2.0.7")
    - matter_version (str): Matter framework version (e.g., "1.0")

Use case:
    Verify which firmware revision is running on a unit before deploying
    updates or diagnosing firmware-related bugs.

This tool queries GET /api/status/system via `SystemApi.get_status_system()` to get
runtime resource usage and health information.

Returns a StatusSystem object containing:
    - api_semver (str): API SemVer string (e.g., "0.0.0")
    - uptime (str): System uptime as a human-readable duration (e.g., "00d 00h 04m 13s")
    - boot_time (int): System boot timestamp as Unix epoch seconds
    - auto_update_enabled (bool): Whether automatic firmware updates are enabled

Use case:
    Monitor available system resources before performing heavy operations (e.g. large
    file uploads or firmware updates) to avoid exhausting the device.

This tool queries GET /api/status/power via `SystemApi.get_status_power()` to check
the current battery and charging state of the unit.

Returns a StatusPower object containing:
    - state (str): Power state — one of "discharging", "charging", or "charged"
    - battery_charge (int): Battery charge level as a percentage (0–100)
    - battery_voltage (int): Battery voltage in millivolts (e.g., 4183 mV)
    - battery_current (int): Battery current in milliamperes; negative means discharging
    - usb_voltage (int): USB input voltage in millivolts (e.g., 4843 mV)

Use case:
    Check battery health before operations that consume significant power;
    alert users when the device needs to be plugged in.

This tool queries /api/time on the device and returns the current date and time
in ISO 8601 format with timezone information (e.g., '2025-10-02T14:30:45+04:00').

Returns a TimestampInfo object containing:
    - timestamp: str  — the current UTC/RFC timestamp in ISO 8601 format

Use case:
    Querying the device's clock as an authoritative time source for scheduling,
    logging, or coordinating events with BUSY timer profiles.

This tool queries /api/time/timezone on the device and returns the currently
active timezone configuration including the display name, UTC offset, and
abbreviation.

Returns a TimezoneInfo object containing:
    - name:  str  — human-readable timezone name (e.g., 'America/New_York')
    - offset: str — UTC offset string (e.g., '-05:00', '+05:30')
    - abbr:   str — timezone abbreviation (e.g., 'EST', 'IST')

Use case:
    Checking which timezone the device is configured to so you can display
    times correctly or decide whether an update is needed.

This tool queries /api/time/tzlist on the device and returns every timezone
that can be used with the set_timezone functionality (/api/time/timezone POST).

Returns a TimezoneListResponse object containing:
    - list:  list[TimezoneInfo]  — an array of available timezones, each with:
        - name:  str  — human-readable timezone name (e.g., 'America/New_York')
        - offset: str — UTC offset string (e.g., '-05:00', '+05:30')
        - abbr:   str — timezone abbreviation (e.g., 'EST', 'IST')

Use case:
    Browsing the available timezones before choosing one to apply via set_timezone.
    Useful for building a UI dropdown or confirming that a specific named timezone is supported.

This tool queries GET /api/update/status via `UpdaterApi.get_firmware_update_status()`
to learn about the current and pending firmware states.

Returns an UpdateStatus object containing:
    - install (UpdateStatusInstall): The currently installed firmware info — version, etc.
    - check (UpdateStatusCheck): Status of the latest automatic or manual update check

Use case:
    Verify which firmware is running and whether a new update has been detected but
    not yet installed — useful for maintenance and rollout planning.

This tool queries GET /api/update/changelog via `UpdaterApi.get_update_changelog(version)`
to obtain release notes and change details for the given firmware version.

Args:
    version: The firmware version string to fetch the changelog for (e.g., "1.0.0").

Returns a GetUpdateChangelog200Response object containing:
    - changelog (str): Human-readable release notes and change log text

Use case:
    Review what changed in a specific firmware revision before deploying updates,
    or compare versions to understand new features and bug fixes.

This tool queries GET /api/update/autoupdate via `UpdaterApi.get_autoupdate_settings()`
to obtain the current autoupdate configuration.

Returns an AutoupdateSettings object containing:
    - is_enabled (bool): Whether automatic updates are enabled
    - interval_start (str): Start of the update window (e.g., "02:00")
    - interval_end (str): End of the update window (e.g., "04:00")

Use case:
    Confirm when or whether firmware updates happen automatically, to avoid unexpected
    reboots during active usage or schedule maintenance around the update window.

This tool queries GET /api/wifi/status via `WiFiApi.api_wifi_status_get()` to obtain
the current network connection details on the Wi-Fi interface.

Returns a StatusResponse object containing:
    - state (str): Connection state — e.g., "connected", "disconnected"
    - ssid (str | null): SSID of the connected access point
    - bssid (str | null): MAC address of the connected access point
    - channel (int): Wi-Fi channel number (e.g., 1, 6, 36)
    - rssi (int): Received signal strength indicator in dBm (negative value)
    - security (str): Security type — e.g., "open", "wpa2", "wpa3"
    - ip_config (StatusResponseIpConfig): IP configuration including:
        - method (WifiIpType): How the IP was obtained ("dhcp" or "static")

Use case:
    Diagnostics for network troubleshooting — verify SSID, signal strength, security
    type, and IP assignment before debugging connectivity issues.

This tool queries GET /api/wifi/networks via `WiFiApi.get_wifi_networks()` to obtain
the latest scan results of available wireless access points in range.

Returns a NetworkResponse object containing:
    - count (int): Number of networks found in the scan
    - networks (list[Network]): Array of network entries, each with SSID, BSSID, RSSI,
      channel, security method, and frequency band information

Use case:
    Browse available Wi-Fi networks before switching the Busy Bar to a different
    access point or confirming signal quality at a new location.