Skip to main content
Glama
Fistacho

ha-nexus-agent

by Fistacho
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Import and validate a blueprint from a URL

blueprints_import_blueprint
Read-onlyIdempotent

Fetch and validate a Home Assistant blueprint from a URL without saving it. Preview metadata and errors before deciding to persist.

Instructions

Fetch a blueprint from a URL and validate it without saving it.

Calls the blueprint/import WebSocket command, which has Home Assistant download url and validate its YAML. This only downloads and validates — it does NOT save anything to disk.

Use when: previewing a blueprint (its metadata and validation errors) before deciding to persist it. Not for: persisting the fetched blueprint — pass its raw_data and suggested_filename to blueprints_save_blueprint. Returns: dict with suggested_filename, raw_data (the blueprint YAML text), blueprint.metadata, validation_errors and exists (whether a blueprint already sits at that path). Limits: blocks for the WebSocket round trip plus the remote download time; the default 10 second response wait in ha._ws_call applies.

Input Schema

NameRequiredDescriptionDefault
urlYesHTTP(S) URL to fetch the blueprint YAML from, e.g. a GitHub raw file link or a community forum export link.
domainNoBlueprint domain the fetched blueprint belongs to, 'automation' or 'script'. Defaults to 'automation'.automation

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.25.1
    • addedInput schema / properties / domain / description
      Added value: +"Blueprint domain the fetched blueprint belongs to, 'automation' or 'script'. Defaults to 'automation'."
    • addedInput schema / properties / url / description
      Added value: +"HTTP(S) URL to fetch the blueprint YAML from, e.g. a GitHub raw file link or a community forum export link."
  2. First observedv0.3.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), yet the description adds non-obvious behavior: it downloads and validates but never persists, the round trip includes a remote download, and the default 10-second ha._ws_call wait applies. That timing/bounding context is genuinely value-add beyond 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 with the core action, then cleanly sectioned into Use/Not for/Returns/Limits. Slightly repetitive in stating non-persistence twice ('does NOT save anything to disk' and 'Not for: persisting'), but every block still carries useful information.

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 two-param, output-schema-bearing tool, the description covers purpose, routing to the alternative, return shape summary, and blocking/timeout limits. Nothing an agent needs in order to call and interpret 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 url and domain are already fully documented with examples and defaults in the schema. The description adds no syntax or format detail beyond that, so the baseline 3 applies; the return-value fields it mentions are outputs, not parameters.

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+resource+scope: 'Fetch a blueprint from a URL and validate it without saving it.' It also names the WebSocket command invoked and contrasts with blueprints_save_blueprint, so an agent can distinguish it from siblings without opening schemas.

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?

Includes explicit 'Use when:' (previewing metadata and validation errors before persisting) and 'Not for:' clauses that route the agent to blueprints_save_blueprint with the exact fields (raw_data, suggested_filename) to pass along. Both the when and the alternative are stated, not inferred.

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