Skip to main content
Glama
Fistacho

ha-nexus-agent

by Fistacho
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Screenshot a Lovelace dashboard view

dashboards_screenshot
Read-onlyIdempotent

Capture a PNG screenshot of a Home Assistant Lovelace dashboard view to visually verify changes after editing.

Instructions

Capture a PNG screenshot of one Lovelace dashboard view via the Puppet add-on engine.

Resolves url_path to a concrete frontend route (see the parameter description), rejects paths containing unsafe characters, then calls the Puppet engine (discovered via Supervisor or NEXUS_SCREENSHOT_ENGINE_URL) over HTTP with the resolved viewport/ zoom/wait parameters and returns its PNG response as base64. Deciding between a dashboard route and a default-dashboard view path costs one lovelace/dashboards/list call (skipped when url_path already starts with lovelace). Reaches only a local/LAN add-on, not the public internet.

Use when: visually verifying a dashboard or view after editing it. Returns: {url_path, engine, format: "png", width, height, image_base64, size_bytes} on success — url_path echoes the resolved route, not the raw argument, and image_base64 can be large, especially with full_page=True (fixed 4096px height). Errors: {"error": "dashboard_list_unavailable" | "invalid_path" | "engine_not_available" | "engine_unreachable" | "engine_http_<code>" | "empty_response", "detail": ..., ...} when the dashboard list can't be fetched, the path is unsafe, the Puppet engine isn't installed/ started, or the engine request itself fails. Limits: 60-second engine timeout; full_page=True only approximates full-scroll capture since the engine does not measure actual page height, so it can crop tall pages or leave blank space on short ones.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
zoomNoBrowser zoom factor applied by the engine. Defaults to 1.0 (no zoom).
widthNoViewport width in pixels. Defaults to 1280.
heightNoViewport height in pixels. Ignored when full_page=True. Defaults to 800.
wait_msNoSettle time in milliseconds after page load before capturing — increase for heavy chart cards. Defaults to 2500.
url_pathNoFrontend route to capture. A registered dashboard's own url_path (e.g. 'dashboard-porch', optionally with a view path appended: 'dashboard-porch/porch-tests') is used as-is. A path already starting with 'lovelace' (e.g. 'lovelace/0') is also used as-is. Anything else is treated as a view of the default dashboard and gets 'lovelace/' prepended (e.g. 'living-room' -> 'lovelace/living-room'). Omit for the default dashboard's root.
full_pageNoIf true, use a fixed 4096px-tall viewport instead of height, approximating a full-scroll capture. Defaults to false.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv0.25.1
    • changedInput schema / properties / full_page / description
      Previous value: -"Capture full scrollable page instead of just the viewport."New value: +"If true, use a fixed 4096px-tall viewport instead of height, approximating a full-scroll capture. Defaults to false."
    • changedInput schema / properties / height / description
      Previous value: -"Viewport height in pixels (default 800)."New value: +"Viewport height in pixels. Ignored when full_page=True. Defaults to 800."
    • changedInput schema / properties / url_path / description
      Previous value: -"Lovelace path, e.g. 'caly-dom' or 'lovelace/0'. Omit for default."New value: +"Frontend route to capture. A registered dashboard's own url_path (e.g. 'dashboard-porch', optionally with a view path appended: 'dashboard-porch/porch-tests') is used as-is. A path already starting with 'lovelace' (e.g. 'lovelace/0') is also used as-is. Anything else is treated as a view of the default dashboard and gets 'lovelace/' prepended (e.g. 'living-room' -> 'lovelace/living-room'). Omit for the default dashboard's root."
    • changedInput schema / properties / wait_ms / description
      Previous value: -"Settle time in ms after load — increase for heavy chart cards (default 2500)."New value: +"Settle time in milliseconds after page load before capturing — increase for heavy chart cards. Defaults to 2500."
    • changedInput schema / properties / width / description
      Previous value: -"Viewport width in pixels (default 1280)."New value: +"Viewport width in pixels. Defaults to 1280."
    • changedInput schema / properties / zoom / description
      Previous value: -"Zoom factor (default 1.0)."New value: +"Browser zoom factor applied by the engine. Defaults to 1.0 (no zoom)."
  2. Addedv0.18.1

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/openWorld status, yet the description adds substantial behavior: unsafe-character rejection, engine discovery order, one extra lovelace/dashboards/list call for ambiguous paths, LAN-only reach, all error variants, and the 60s timeout plus full_page approximation caveat.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action, then organizes the rest into Use/Returns/Errors/Limits blocks, so every section earns its place. It is dense but not padded, though it is longer than strictly necessary given the output schema exists.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a screenshot tool with six parameters, an output schema, and annotations, the description covers resolution behavior, error taxonomy, and limits without contradicting structured fields. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameters are already fully documented, including url_path resolution and full_page semantics. The description largely restates the url_path resolution rule rather than adding new syntax beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (capture PNG screenshot), resource (Lovelace dashboard view), and mechanism (Puppet add-on engine). An agent can distinguish this from siblings like dashboards_list_dashboards or snapshot_get_snapshot without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit 'Use when: visually verifying a dashboard or view after editing it' gives clear triggering context. No explicit when-not or named alternative is offered, but the usage condition is unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools