Skip to main content
Glama
Vectorworks MCP

Vectorworks MCP

vw_lightwright_patch

Write Lighting Device field changes as a Lightwright Data Exchange patch beside the Vectorworks file when the direct bridge is blocked, then verify the applied results.

Instructions

Change Lighting Device fields through Spotlight's Lightwright Data Exchange file instead of a job, for Lightwright round trips or when a dialog blocks the bridge.

With dry_run=False this changes the document, indirectly: the patch is written beside the .vwx and Vectorworks applies it 1 to 2 s after it next gains focus, so the user has to click into Vectorworks; verify afterwards with vw_list_lighting_devices. Prefer vw_set_lighting_device_fields when the bridge works. Refuses deletes, fields not in the export, a Symbol_Name no fixture uses yet (an unknown symbol breaks fixture selection drawing-wide, irreversibly) and a type change without Wattage. Before writing, the full export is copied to ~/.vwmcp/lightwright/ (backup) and the drawing's current values of the touched fixtures are journaled (inverse_from: live, or export when a fixture could not be read, in which case the undo restores possibly stale export values); vw_revert_last writes the inverse patch, which again needs a click. After a patch the file holds only Vectorworks' acknowledgement until the next full export. Returns {dry_run, path, changes, patch, and when written: backup, inverse_from, note}.

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": {
      "changes": "<changes>"
    },
    "name": "vw_lightwright_patch"
  }
}

Input Schema

NameRequiredDescriptionDefault
changesYesOne item per fixture: {"uid": "1246.1.1.0.0", "fields": {"Channel": "201"}}. `uid` and the field names (exchange spelling: Channel, Unit_Number, Inst_Type, Purpose, Color ...) come from vw_lightwright_snapshot; only fields in the export can be written, plus Symbol_Name, Inst_Type and Wattage.
dry_runNoTrue (default) returns the patch text without writing anything; False writes it.
documentNoName of the document this call is meant for (as vw_list_documents shows it, with or without .vwx). If another document is active nothing changes; use vw_switch_document first. Always set it for a write.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.1.1
    • addedInput schema / properties / changes / description
      Added value: +"One item per fixture: {\"uid\": \"1246.1.1.0.0\", \"fields\": {\"Channel\": \"201\"}}. `uid` and the field names (exchange spelling: Channel, Unit_Number, Inst_Type, Purpose, Color ...) come from vw_lightwright_snapshot; only fields in the export can be written, plus Symbol_Name, Inst_Type and Wattage."
    • addedInput schema / properties / document / description
      Added value: +"Name of the document this call is meant for (as vw_list_documents shows it, with or without .vwx). If another document is active nothing changes; use vw_switch_document first. Always set it for a write."
    • addedInput schema / properties / dry_run / description
      Added value: +"True (default) returns the patch text without writing anything; False writes it."
  2. Added

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations: the write is indirect and delayed 1-2 s until Vectorworks gains focus, requiring a user click; the export is copied to ~/.vwmcp/lightwright/ as `backup`; touched fixtures are journaled as `inverse_from` (live, or stale export values when unreadable); and after a patch the file holds only an acknowledgement until the next full export. It also explains why an unknown Symbol_Name is refused (drawing-wide irreversible breakage of fixture selection).

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-loaded with purpose and the preferred alternative, then the refusal list and side effects. Dense and mostly earned, but several sentences are run-on with stacked parentheticals (the inverse_from aside, the acknowledgement note) that cost a little readability.

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?

No output schema exists, and the description explicitly enumerates the return keys ({dry_run, path, changes, patch, and when written: backup, inverse_from, note}). Given the tool's complexity (indirect, deferred mutation with rollback), the description covers mechanism, prerequisites, refusals, recovery, and verification without gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the schema already documents `changes`, `dry_run`, and `document` in detail, so the baseline applies. The description only restates the dry_run=True/False meaning and references the uid/field spelling indirectly; it adds no new syntax or constraint beyond the schema.

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 target (changing Lighting Device fields) plus the exact mechanism (Spotlight's Lightwright Data Exchange file rather than a job) and the two scenarios that motivate it (Lightwright round trips, dialog blocking the bridge). It is immediately distinguishable from vw_set_lighting_device_fields and vw_lightwright_snapshot, which are named in the text.

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?

Gives explicit routing: 'Prefer vw_set_lighting_device_fields when the bridge works.' Adds a prerequisite ('use vw_switch_document first' / always set document for a write) and a post-condition check ('verify afterwards with vw_list_lighting_devices'). Exclusions are stated too: it refuses deletes, fields not in the export, unknown Symbol_Name, and type changes without Wattage.

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