ha-nexus-agent

Overview Schema Source Related Servers Discussions Admin

Upload media to Card Builder library

card_builder_upload_media

DestructiveIdempotent

Upload base64-encoded image bytes to the Card Builder media directory. Converts in-memory content into a public file and returns a reference for block-image use.

Instructions

Upload base64-encoded bytes as a file in the Card Builder media directory.

Decodes content_base64 and writes it under www/card_builder/<path>/ <filename> via card_builder/media/upload. filename must be a bare name (no /, \, or ..) with an allowed extension — .png, .jpg, .jpeg, .gif, .webp, .svg, .avif (case-insensitive). A .svg filename gets its decoded content sanitized (script/handler/ unsafe-URL stripping, element-count cap) — see sanitize_svg. The file becomes **public** under /local/ with **no authentication**, same origin as the HA frontend. Upstream's _write_media_file writes with no existence check, so uploading onto an existing filename/ path silently overwrites it, with no backup.

Use when: the file bytes are already in memory (e.g. generated inline). Not for: a file already on the HA config filesystem — use card_builder_upload_media_from_path; a remote image — use card_builder_upload_image_from_url; raw SVG you'd rather not base64-encode — use card_builder_upload_svg. Returns: {reference, path, url} — reference is the cb-media://local/card_builder/<filename> URI for a block-image's mediaReference prop. Errors: {"error": "extension_not_allowed" | "invalid_base64" | "file_too_large" | "invalid_svg" | ...} (plus sanitize_svg errors) when validation or sanitization rejects the input. Limits: decoded content over _MAX_MEDIA_UPLOAD_BYTES (15 MiB) is refused.

Input Schema

TableJSON Schema

Name	Required	Description
`path`	No	Sub-folder under www/card_builder/ to upload into. Empty string uploads to the root.
`filename`	Yes	Bare target filename with an allowed image/SVG extension, e.g. 'bg-1.png'. No path separators.
`content_base64`	Yes	Raw file bytes, base64-encoded.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.25.1Oct 4, 2026

addedInput schema / properties / content_base64 / description
```
Added value: +"Raw file bytes, base64-encoded."
```

addedInput schema / properties / filename / description

Added value: +"Bare target filename with an allowed image/SVG extension, e.g. 'bg-1.png'. No path separators."

addedInput schema / properties / path / description

Added value: +"Sub-folder under www/card_builder/ to upload into. Empty string uploads to the root."

Addedv0.18.1Jun 19, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations (destructiveHint=true, idempotentHint=true, openWorldHint=false) cover the safety profile, and the description adds substantial context beyond them: files become public under /local/ with no authentication, existing files are silently overwritten with no backup (matching destructiveHint), SVG content is sanitized, and the 15 MiB limit plus error codes are disclosed. No contradiction with idempotentHint/destructiveHint.

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 layered into constraints, use/not-for, returns, errors, and limits. Dense but well-structured; a few phrases (e.g. repeating the path template) border on redundancy, keeping it short of a 5.

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?

Even though an output schema exists, the description supplies the public-exposure/authentication implication, overwrite semantics, sanitization behavior, size cap, and error taxonomy — everything an agent needs to call this correctly and predict side effects. Nothing material is missing.

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 coverage is 100%, so baseline is 3, but the description adds real constraints not in the schema: filename must be a bare name with no '/', '\' or '..', the exact allowed extension list is enumerated, and extension matching is case-insensitive. It also clarifies path is the sub-folder under www/card_builder/. Marginal gain over the schema, but genuine.

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 (upload), resource (base64-encoded bytes as a file), and target location (Card Builder media directory under www/card_builder/<path>/<filename>). It also explicitly distinguishes itself from the three sibling upload tools (upload_media_from_path, upload_image_from_url, upload_svg) without the agent needing to open any 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 an explicit 'Use when: the file bytes are already in memory' plus a 'Not for' list naming the correct alternative for each excluded case (on-disk file, remote image, raw SVG). This is exactly the when/when-not/alternatives pattern.

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

Deploy Server