Skip to main content
Glama

Change elements

update
Destructive

Modify properties of design elements like walls, furniture, and rooms by ID, with optional dry-run preview and bulk regex renaming.

Instructions

Change fields of elements by id; each field applies only to the kinds that have it (furniture mat/opacity/pitch, wall h_end, room auto/ceiling_flat, polyline divider). A part of a group takes name, brand, model_name and url on its own; its size and place belong to the group. anchor on a resize holds one face still instead of growing around the center; stretch=[part ids] on a group resize grows only those parts and moves the rest along (uprights keep 5.8 cm while the opening grows). dry=true answers what it would do without writing: changed fields, clearances around each piece it touches (negative: cm it would sit inside what it faces), issues_resolved/issues_new [{ids, kind, extent|cm|over}] with the kinds layout gives, and issues_changed (extent_was); dry="summary" leaves out the parts a group rebuilds. Otherwise the reply names what changed. rename {pattern, to, what} renames in bulk by a regex (Rust syntax, (?i) for any case, $1 in to) in one step; with dry it lists them first.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
vNoPlan version (tab) to write to; switches to it first
dryNoAnswer what it would change, without writing
itemsNoThe elements to change, one object each: `id` and the fields to set
renameNoRename in bulk by a regex, in one step

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
vNo
okNo
dryNo
idsNo
revNo
goneNo
textNo
addedNo
scoreNo
changedNo
resolvedNo
unchangedNo
clearancesNo
issues_newNo
propertiesNo
added_countNo
annotationsNo
score_scopeNo
new_findingsNo
changed_countNo
issues_changedNo
unchanged_noteNo
issues_resolvedNo
findings_changedNo
acceptance_cleanupNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed43 schema fields changedv3.0.0
    • changedInput schema / $defs / Dry / description
      Previous value: -"Runs an edit against a copy of the plan and reports what it would do. Trying a size used to mean applying it, reviewing, and undoing — a round trip that showed in the user's window and burned a revision each time. The copy has no history and is thrown away, so nothing of that happens. How much of a dry run to answer with. `true` answers with everything it would change; `\"summary\"` answers with the decision — how many pieces move, which roots, the clearances, the findings and the score — because a group that rebuilds lists ninety-seven parts for a choice that fits in five lines"New value: +"How much of a dry run to answer with: `true` everything it would change, `\"summary\"` the decision — pieces moved, roots, clearances, findings, score"
    • changedInput schema / $defs / LightSpec / properties / z / description
      Previous value: -"Source height as a fraction of the piece's height (default: its base for spots and panels, the middle otherwise)"New value: +"Source height, fraction of the piece's (default: base for spots and panels, else middle)"
    • changedInput schema / $defs / Point2 / description
      Previous value: -"[x, y] in centimeters; x grows right, y grows down"New value: +"[x, y] cm"
    • removedInput schema / $defs / RenameSpec / properties / to / default
      Removed value: -""
    • changedInput schema / $defs / RenameSpec / properties / what / description
      Previous value: -"`names` (default: pieces and the parts of groups) or `labels`"New value: +"Default `names`, parts of groups included"
    • addedInput schema / $defs / RenameSpec / properties / what / enum
      Added value: +[
      +  "names",
      +  "labels"
      +]
    • changedInput schema / $defs / RoomUse / description
      Previous value: -"Declared room program, independent of its display name. Auto preserves legacy name/equipment inference; other values are explicit intent"New value: +"Declared room program; `auto` infers it from the name and equipment"
    • changedInput schema / $defs / UpdateSpec / description
      Previous value: -"Fields that can be changed on an element. Each applies only to the kinds that have it; anything else — a field that does not exist included — is rejected so mistakes are loud"New value: +"Fields to change; each applies only to the kinds that have it, and any other is refused"
    • changedInput schema / $defs / UpdateSpec / properties / about / description
      Previous value: -"The piece a note is about, e.g. `f1185`; its numbers are then checked against that piece by `annotations(stale=true)`. `\"\"` unties it"New value: +"The piece a note is about (e.g. `f1185`), checked by `annotations` stale; `\"\"` unties it"
    • changedInput schema / $defs / UpdateSpec / properties / anchor / description
      Previous value: -"Which face of the piece stays put when `w`, `d` or `h` change: `back`, `front`, `left`, `right` (relative to the way it faces), `bottom`, `top`, or a plan side `+x`, `-x`, `+y`, `-y`. Without it a resize grows around the center and both faces move, which is almost never what a run of joinery wants"New value: +"Face that stays put on a resize: `back`, `front`, `left`, `right` (as the piece faces), `bottom`, `top`, or `+x`, `-x`, `+y`, `-y`; default the center"
    • changedInput schema / $defs / UpdateSpec / properties / ceiling_flat / description
      Previous value: -"Room ceiling mode: true is flat at storey height; false follows wall profiles. Lower roof panels clip either mode; ceiling controls visibility separately"New value: +"Room ceiling flat at storey height (true) or following the wall profiles (false)"
    • changedInput schema / $defs / UpdateSpec / properties / fixed / description
      Previous value: -"Furniture: `true` fixed joinery (a top that can host a built-in outlet), `false` free-standing, when its name does not say; `\"\"` takes the declaration back and lets the name decide again"New value: +"Furniture: `true` fixed joinery, `false` free-standing; `\"\"` lets the name decide"
    • changedInput schema / $defs / UpdateSpec / properties / layer / description
      Previous value: -"Plan layer of a piece: `lighting`, `appliances`, `joinery`, `none` (in no layer), or empty to go back to the layer it is in by itself"New value: +"Plan layer: `lighting`, `appliances`, `joinery` or `none`; empty restores its own"
    • changedInput schema / $defs / UpdateSpec / properties / role / description
      Previous value: -"Functional role independent of name: `trim`, `backsplash`, `counter`; empty restores automatic classification. Does not disable collisions"New value: +"Role independent of the name: `trim`, `backsplash`, `counter`, `stair`; empty: automatic"
    • changedInput schema / $defs / UpdateSpec / properties / stretch / description
      Previous value: -"On a group resize, the parts that take the change (ids); every other part keeps its size and moves along. Without it the group scales all its parts by the same factor"New value: +"On a group resize, the parts that take the change; the others keep their size"
    • changedInput schema / properties / dry / description
      Previous value: -"Try it without applying: reports what would change, the clearances around every piece it touches, and which layout and ergonomics findings it would resolve or create. Nothing is written and the user's window does not move"New value: +"Answer what it would change, without writing"
    • removedInput schema / properties / items / default
      Removed value: -[]
    • changedInput schema / properties / rename / description
      Previous value: -"Rename in bulk by a rule instead of listing items: every name (pieces and the parts of groups) or label text matching `pattern` has it replaced by `to`, in one undoable step"New value: +"Rename in bulk by a regex, in one step"
    • removedOutput schema / properties / acceptance_cleanup / description
      Removed value: -"Acceptances orphaned, and the calls that clear them"
    • removedOutput schema / properties / added / description
      Removed value: -"Ids added, or their count"
    • removedOutput schema / properties / added_count / description
      Removed value: -"Roots added"
    • removedOutput schema / properties / annotations / description
      Removed value: -"Annotation switches {from, to}"
    • removedOutput schema / properties / changed / description
      Removed value: -"{id, from, to} per element changed; a count past 20"
    • removedOutput schema / properties / changed_count / description
      Removed value: -"Roots changed"
    • removedOutput schema / properties / clearances / description
      Removed value: -"Free floor around touched pieces, by id"
    • removedOutput schema / properties / dry / description
      Removed value: -"Nothing was written"
    • removedOutput schema / properties / findings_changed / description
      Removed value: -"Findings changed"
    • removedOutput schema / properties / gone / description
      Removed value: -"Ids removed, or their count"
    • removedOutput schema / properties / ids / description
      Removed value: -"Ids created or touched"
    • removedOutput schema / properties / issues_changed / description
      Removed value: -"Layout issues resized"
    • removedOutput schema / properties / issues_new / description
      Removed value: -"Layout issues created"
    • removedOutput schema / properties / issues_resolved / description
      Removed value: -"Layout issues settled"
    • removedOutput schema / properties / new_findings / description
      Removed value: -"Findings created"
    • removedOutput schema / properties / ok / description
      Removed value: -"Always true"
    • removedOutput schema / properties / properties / description
      Removed value: -"Project properties changed"
    • removedOutput schema / properties / resolved / description
      Removed value: -"Findings settled"
    • removedOutput schema / properties / rev / description
      Removed value: -"Plan revision"
    • removedOutput schema / properties / score / description
      Removed value: -"Score [before, after]"
    • removedOutput schema / properties / score_scope / description
      Removed value: -"Disciplines scored"
    • removedOutput schema / properties / text / description
      Removed value: -"The reply as written"
    • removedOutput schema / properties / unchanged / description
      Removed value: -"Asked ids that came out as they were: {id, now}"
    • removedOutput schema / properties / unchanged_note / description
      Removed value: -"Why they did not change"
    • removedOutput schema / properties / v / description
      Removed value: -"Plan version written to, when there are several"
  2. First observedv0.1.0

TDQS

A3.8/5.0
Behavior5/5

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

The description goes far beyond annotations: it details dry-run behavior (what is returned, clearances, issues), group vs part mutation rules, anchor and stretch semantics, and bulk rename via regex. It clearly discloses destructive effects and the non-writing dry option, matching the destructiveHint annotation without contradiction.

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 action and remains dense with relevant detail for a complex tool. It is a single long paragraph without formatting breaks, but nearly every clause carries useful constraint or behavior information and none is obviously filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich input schema, destructive annotation, and existing output schema, the description covers most behavioral needs: dry runs, group/part rules, anchor/stretch, and rename. It omits explanation of the 'v' version parameter and the optional 'items' container (including what happens if items is empty), which are minor but noticeable gaps 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%, but the description adds substantial cross-parameter meaning: group parts take name/brand/model_name/url individually while size and place belong to the group, anchor holds a face on resize, stretch selects group parts, and dry values control response detail. It does not document every field, but adds semantics that the schema alone does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Change fields of elements by id'. It clarifies that fields apply only to certain kinds, but does not explicitly differentiate from sibling tools like edit_walls, edit_model, or move, leaving some ambiguity about when this general updater is preferred over specialized editors.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives such as edit_walls, move, or create. The description explains internal parameter behavior (dry run, rename, group semantics) but never states context or routing conditions for selecting this tool over siblings.

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