Skip to main content
Glama
Fistacho

ha-nexus-agent

by Fistacho
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Create theme file

themes_create_theme
DestructiveIdempotent

Create a new Lovelace theme file in Home Assistant, writing themes/.yaml and reloading themes. Fails if the theme exists unless overwrite is true.

Instructions

Create a new Lovelace theme file.

Writes themes/<name>.yaml as {<name>: variables}. The file is only loaded by the frontend if configuration.yaml has frontend: themes: !include_dir_merge_named themes. Fails instead of overwriting unless overwrite=True.

Use when: adding a brand-new theme. Not for: changing an existing theme in place — use themes_update_theme. Returns: dict with success, path, and reloaded (present when reload=True). Errors: {"success": false, "error": "Theme '<name>' already exists. Pass overwrite=True to replace."} when the file exists and overwrite is false; {"success": false, "error": "invalid_theme_name", "detail": ...} when name contains '/' or a backslash, starts with '.', or is blank. Limits: name must not contain '/' or a backslash, start with '.', or be blank.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameYesTheme name, becomes the filename themes/<name>.yaml without the extension.
reloadNoIf true, calls frontend.reload_themes after writing the file; defaults to true.
overwriteNoIf true, replaces an existing theme file instead of failing; defaults to false.
variablesYesInner theme variable map to write, e.g. {'primary-color': '#03a9f4'} or a 'modes' block with 'light'/'dark' keys; not wrapped in the theme name.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.25.1
    • addedInput schema / properties / name / description
      Added value: +"Theme name, becomes the filename themes/<name>.yaml without the extension."
    • addedInput schema / properties / overwrite / description
      Added value: +"If true, replaces an existing theme file instead of failing; defaults to false."
    • addedInput schema / properties / reload / description
      Added value: +"If true, calls frontend.reload_themes after writing the file; defaults to true."
    • addedInput schema / properties / variables / description
      Added value: +"Inner theme variable map to write, e.g. {'primary-color': '#03a9f4'} or a 'modes' block with 'light'/'dark' keys; not wrapped in the theme name."
  2. Addedv0.4.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare the safety profile (not read-only, destructive, idempotent, closed-world). The description adds materially more: the fail-instead-of-overwrite default, the configuration.yaml `frontend: themes: !include_dir_merge_named` prerequisite for the file to actually load, the reload behavior, and two concrete error shapes. That is real behavioral context beyond the structured fields.

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-loaded purpose sentence followed by clearly labeled Writes/Use when/Not for/Returns/Errors/Limits sections, so scanning is easy. The one weakness is redundancy: the invalid-name constraint appears twice (Errors and Limits), and Returns restates information the output schema already carries.

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 mutating, nested-object tool with an output schema present, the description covers the file-path convention, the config prerequisite, overwrite/reload semantics, and both failure modes. Nothing an agent needs to invoke it correctly is missing, and return values are described even though the output schema already handles them.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3 and the schema already explains name, reload, overwrite, and variables. The description still adds value by translating `name` validation into observable failure modes ('/' or backslash, leading '.', blank) and by restating the overwrite default in outcome terms, which is more than the schema alone conveys.

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 and resource (create a Lovelace theme file) and even names the exact artifact written (`themes/<name>.yaml` as `{<name>: variables}`). It explicitly distinguishes itself from the sibling `themes_update_theme`, so an agent can route without opening either schema.

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

Usage Guidelines5/5

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

Contains explicit 'Use when: adding a brand-new theme' and 'Not for: changing an existing theme in place — use themes_update_theme', naming the alternative and the condition that selects it. This is the textbook when/when-not/alternative pattern.

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