ha-nexus-agent

Overview Schema Source Related Servers Discussions Admin

Remove card from dashboard section

dashboards_remove_card_from_section

Destructive

Remove a card from a Home Assistant sections dashboard view by section and card index. Pass a config hash to avoid deleting a shifted card when data is stale.

Instructions

Delete one card from a section of a type: sections view.

Resolves the view and section via _load_view/_require_section, pops the card at card_index from that section's cards list, and saves the whole dashboard back. card_index is a position, not a stable id — repeating this call with the same section_index/ card_index after a first successful removal deletes whatever card has shifted into that position next, not a no-op, unless expected_config_hash is also passed and now points at the pre-removal hash, in which case the repeat is rejected with config_changed instead of deleting the wrong card.

Use when: removing a card that's no longer wanted on a sections view. Pass expected_config_hash whenever section_index/card_index came from an earlier read that might now be stale. Returns: {status: "removed", url_path, view_index, view_title, section_index, card_index, removed_card, cards_in_section, config_hash} — removed_card can be passed back to dashboards_add_card_to_section to restore it; config_hash is re-read from HA after the save, ready to chain into the next call's expected_config_hash. Errors: raises ValueError when the view/section/card can't be resolved (bad index/path). Returns {"error": "config_changed", "expected_config_hash", "current_config_hash", "action"} without saving when expected_config_hash doesn't match.

Input Schema

TableJSON Schema

Name	Required	Description
`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.
`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 removes nothing — this is what makes a repeated call with a now-stale hash safe instead of deleting whatever shifted into that position. 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.6/5.0

Behavior5/5

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

The description goes well beyond the annotations: it discloses that repeating the call after a successful removal will delete a different card unless expected_config_hash guards it, describes the internal resolution steps, the return shape, and specific error conditions (ValueError for bad indices, config_changed error without saving). This is critical context for a destructive, non-idempotent operation.

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?

The description is front-loaded with the core purpose and key caveat about positional indexing, then details usage, return, and errors in a structured way. It is somewhat lengthy but every sentence adds valuable information, making it well-organized and useful despite the length.

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?

Given the destructive and non-idempotent nature, the description covers all essential aspects: usage, safety guard with expected_config_hash, return format, error behavior, and the non-obvious positional deletion risk. Combined with an output schema, it is fully complete for correct invocation.

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 the baseline is 3; however, the description adds significant semantic nuance by clarifying that card_index is a position not a stable ID and explaining the role of expected_config_hash in preventing accidental deletion, which enhances understanding beyond the schema descriptions.

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?

The description states a specific verb (delete/remove) and resource (a card from a section of a type: sections view), and distinguishes itself from siblings like dashboards_add_card_to_section and dashboards_update_card_in_section by noting the removal action and the positional nature of the operation.

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?

It provides a clear 'Use when' clause and an important warning about passing expected_config_hash when indices come from a potentially stale read. It doesn't explicitly name alternative tools for related tasks, but the primary usage condition and a key safety condition are covered.

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

Deploy Server