Skip to main content
Glama

Save NeonPlan 3D plan

neonplan_save_plan
DestructiveIdempotent

Replace a complete NeonPlan 3D plan for full rebuilds: validate first, enforce revision checks, take a restore point when needed, then save and verify by reading back.

Instructions

Replace a whole NeonPlan 3D plan after validating it, with a restore point and a read-back check.

Runs neonplan_validate_plan (any error blocks), refuses a plan with floors unless overwrite, checks expected_revision, takes a restore point (history/snapshot) when the plan has floors, reads the revision again, sends neonplan3d/building/save and reads the plan back. The integration itself has no revision check: an editor open with unsaved changes (see neonplan_get_status screens) can still overwrite this.

Use when: building a plan from scratch or replacing it entirely. Not for: small edits — use neonplan_patch_plan; undo — use neonplan_restore_restore_point. Returns: {"saved": true, "plan", "revision_before", "revision", "snapshot_taken", "verified", "differences", "summary", "warnings"}. Errors: validation_failed (with errors), plan_not_empty, revision_conflict, invalid_building (the server's schema refused), 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": {
      "building": "<building>"
    },
    "name": "neonplan_save_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).
buildingYesThe complete building object (version, settings, floors, ...); it replaces the stored one.
overwriteNoTrue allows replacing a plan that already has floors; false refuses that.
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.8/5.0
Behavior5/5

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

Goes well beyond the annotations by disclosing the full execution pipeline: validation blocking, the floors/`overwrite` refusal, the restore-point snapshot, the read-back verification, and the specific save endpoint. Crucially it warns that the integration itself has no revision check and an editor with unsaved changes can still be overwritten — a race condition the `destructiveHint` alone would not convey.

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?

Strongly front-loaded and segmented with Use when / Not for / Returns / Errors labels, and the procedure sentence earns its density by naming the actual endpoints and checks. The long run-on pipeline paragraph is harder to scan than the rest, and the Returns list partially duplicates the output schema.

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, nested-object mutation with a multi-step internal workflow, the description covers preconditions, side effects, the race caveat, the enumerated error codes, and the response shape. Nothing an agent needs to decide whether and how to call it 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 the baseline is 3, but the description adds real meaning: `overwrite` is tied to the floors precondition and `expected_revision` is framed as a compare-before-write guard from the caller's last read. It does not explain `force` (the version-bypass flag) or that `plan` defaults to `main`, which keeps it from a 5.

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 and resource ("Replace a whole NeonPlan 3D plan") and immediately scopes it against siblings: "Not for: small edits — use `neonplan_patch_plan`; undo — use `neonplan_restore_restore_point`." An agent can distinguish this from patch, validate, and restore without opening 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?

Provides an explicit "Use when: building a plan from scratch or replacing it entirely" and paired exclusions with named alternatives for edits and undo. It also states prerequisites implicitly through the validation gate and the `overwrite`/`expected_revision` conditions that must be satisfied.

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