ha-nexus-agent

Overview Schema Source Related Servers Discussions Admin

Update card in dashboard section

dashboards_update_card_in_section

Destructive

Update one existing card in a Home Assistant sections view by merging changes or replacing it, with optional config hash guard against stale edits.

Instructions

Change one existing card inside a section of a type: sections view.

Resolves the view and target card via _load_view/_require_card, then merges card_config's keys into the existing card (merge=True, the default) or replaces it outright (merge=False), and saves the whole dashboard back. The previous card is only recoverable via card_before in this call's own response — storage itself keeps no history. With expected_config_hash, the dashboard's hash is checked right after the read and before any change, so a stale caller can't edit the wrong card.

Use when: tweaking or replacing one card already placed in a section. Pass expected_config_hash when section_index/card_index came from a read that might now be stale. Not for: adding a new card — use dashboards_add_card_to_section; removing one — use dashboards_remove_card_from_section. Returns: {status: "updated", url_path, view_index, view_title, section_index, card_index, card_before, card_after, config_hash} — config_hash is re-read from HA after the save, for the next call's expected_config_hash. Errors: raises ValueError when card_config is empty, merge=False lacks a type key, or the view/section/card can't be resolved. Returns {"error": "config_changed", ...} without saving when expected_config_hash doesn't match.

Input Schema

TableJSON Schema

Name	Required	Description
`merge`	No	If true (default), merge card_config's keys into the existing card. If false, replace the card wholesale.
`url_path`	Yes	Dashboard url_path, or a view path in the default dashboard (e.g. 'living-room').
`card_index`	Yes	Zero-based card index within the section, from dashboards_get_view_sections/inspection.
`view_index`	No	Zero-based view index; needed only when url_path names a dashboard rather than a view path.
`card_config`	Yes	Card fields to apply. With merge=true, a partial update (only these keys change); with merge=false, the full replacement card (needs a 'type' key).
`section_index`	Yes	Zero-based section index, from dashboards_get_view_sections.
`expected_config_hash`	No	Optional guard: the config_hash from a recent dashboards_get_view_sections or section-tool response. If the dashboard's current hash differs, this call returns 'config_changed' and saves nothing, since section_index/card_index are positions, not stable ids, and a change since your read may target the wrong card. Omit to skip the check (today's behaviour).

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.25.1Oct 4, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Goes well beyond annotations: explains merge vs. replace semantics, that no history exists so the prior card is recoverable only via `card_before` in this response, that the hash check occurs after read and before any write, and the exact failure modes (`config_changed`, ValueError conditions).

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 purpose, then behavior, usage routing, return shape, and errors in labeled blocks; dense but nearly every sentence carries unique information, with only minor overlap against the schema's merge description.

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 destructive, non-idempotent mutation with a nested config object, the description covers side effects, rollback limits, guard semantics, error cases, and return fields; an output schema exists, so summarizing returns is a bonus rather than a requirement.

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; the description adds meaning beyond the schema by tying `expected_config_hash` to stale-index risk and clarifying that `merge=True` is the default partial-update path while `merge=False` requires a `type` key.

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 precise verb and resource with scope ('Change one existing card inside a section of a `type: sections` view'), and explicitly names the sibling tools for adjacent operations (add/remove), so an agent can route correctly 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?

Provides explicit 'Use when' and 'Not for' clauses naming `dashboards_add_card_to_section` and `dashboards_remove_card_from_section`, plus conditional guidance on when to pass `expected_config_hash` (stale index risk).

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

Deploy Server