Skip to main content
Glama

Patch NeonPlan 3D plan

neonplan_patch_plan
Destructive

Edit part of an existing NeonPlan 3D plan using JSON Patch operations, then validate and save it with revision guards and a restore point. Use it to bind entities, add lamps or windows, or rename rooms.

Instructions

Change part of a NeonPlan 3D plan with JSON Patch operations, then validate and save it like neonplan_save_plan.

Reads the plan, applies the operations to a copy (a failing operation, including a failed test, stops everything), validates the result (errors block) and saves it with the same guards as neonplan_save_plan: expected_revision, restore point, revision re-check, read-back. An operation on path "" (the whole plan) needs overwrite=true when the plan has floors, like neonplan_save_plan.

Use when: binding an entity, adding a lamp or window, renaming a room — any edit of an existing plan. Not for: a new plan from scratch — use neonplan_save_plan; checking paths first — read with neonplan_get_plan. Returns: like neonplan_save_plan, plus "operations" (count). Errors: invalid_patch (with operation index), validation_failed, plan_not_empty (whole-plan operation without overwrite), revision_conflict, invalid_building, neonplan_version_unsupported, invalid_plan, plan_not_found, admin_required, neonplan_not_installed, ha_unreachable.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "operations": "<operations>"
    },
    "name": "neonplan_patch_plan"
  }
}

Input Schema

NameRequiredDescriptionDefault
planNoPlan id from `neonplan_list_plans`; `main` (default) is the plan every install has.main
forceNoTrue writes even when the integration is not version 3.0.x (format checked by you).
overwriteNoTrue allows an operation on path '' (the whole plan) when the plan has floors, as save_plan.
operationsYesJSON Patch (RFC 6902) operations on the building, applied in order, e.g. `[{"op": "replace", "path": "/floors/0/openings/2/cover", "value": "cover.blind_kitchen"}, {"op": "add", "path": "/floors/0/furniture/-", "value": {...}}]`; ops add, remove, replace, move, copy, test.
expected_revisionNo`revision` from your last read; if the plan's revision differs, nothing is written.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.29.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only say destructiveHint=true and not idempotent; the description goes far beyond that by disclosing the atomic-copy semantics (a failing op including a failed `test` stops everything), that validation errors block the save, and the full guard chain (expected_revision, restore point, revision re-check, read-back). It also documents the `overwrite=true` requirement for whole-plan path '' and enumerates the concrete failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the action in the first sentence, then uses labeled sections (behavior, Use when, Not for, Returns, Errors) that let an agent skim. The error enumeration is long but each entry is a distinct actionable code, so the length is earned.

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, five-parameter mutation tool, the description covers preconditions, atomicity, guard behavior, return delta ('operations' count) and the error surface. With an output schema present it doesn't need to describe the payload shape, and nothing an agent needs to invoke it safely 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 3 would be the baseline, but the description adds real meaning: it clarifies that the whole-plan path '' interacts with the `overwrite` flag when floors exist, and that `invalid_patch` reports an `operation` index so the caller knows which op failed. It does not restate op syntax or field formats beyond what the schema already documents.

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?

Opens with a specific verb and resource ('Change part of a NeonPlan 3D plan with JSON Patch operations') and immediately ties itself to the sibling it mirrors, `neonplan_save_plan`. An agent can distinguish patch-editing an existing plan from creating one or validating one purely from the description.

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?

Has explicit 'Use when' examples (binding an entity, adding a lamp or window, renaming a room) and an explicit 'Not for' clause routing new plans to `neonplan_save_plan` and path inspection to `neonplan_get_plan`. Both the positive trigger and the excluded alternatives are named.

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