Skip to main content
Glama
Vectorworks MCP

Vectorworks MCP

vw_import_hookup

Imports channel hookups or instrument schedules from CSV/TSV exports into Vectorworks Lighting Devices, previewing planned changes first and applying them as one revertible, all-or-nothing update.

Instructions

Load a channel hookup or instrument schedule from a spreadsheet export into the Lighting Devices, as a dry run first and then one revertible step.

Changes the document only with dry_run=False. Each row is matched to exactly one device by key; the other columns are written as Lighting Device fields when their header is a field name, unknown headers are ignored and listed, empty cells are not written. The dry run returns {dry_run, rows, updates (the planned per-device changes), ignored_columns, skipped_rows, next_step}. Applying goes through vw_set_lighting_device_fields: all-or-nothing (a row that matches no device, or several, stops everything), undone with vw_revert_last, with result holding before/after and not_applied for values Spotlight overrode. For a handful of edits call vw_set_lighting_device_fields directly.

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": {
      "path": "<path>"
    },
    "name": "vw_import_hookup"
  }
}

Input Schema

NameRequiredDescriptionDefault
keyNoWhich column(s) identify the device each row belongs to: "channel" (default, the Channel column), "unit_number" (only when unit numbers are unique in the whole plot) or "position+unit_number" (Position and Unit Number columns together; unit numbers repeat per position).channel
pathYesPath on this Mac to a .csv or .tsv exported from the spreadsheet; the first row holds the column headers.
dry_runNoTrue (default) changes nothing and returns the plan to show the user; False applies it and then needs `document`.
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. Required when dry_run is False.
column_mapNoSpreadsheet header to Lighting Device field name, for headers the automatic match does not understand, for example {"What": "Purpose"}. Automatic matches are case-insensitive and know Address/Addr/DMX (UniverseAddress), Unit (Unit Number), Inst/Type (Inst Type) and Gel (Color). Omit when the headers are field names.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.1.1
    • addedInput schema / properties / column_map / description
      Added value: +"Spreadsheet header to Lighting Device field name, for headers the automatic match does not understand, for example {\"What\": \"Purpose\"}. Automatic matches are case-insensitive and know Address/Addr/DMX (UniverseAddress), Unit (Unit Number), Inst/Type (Inst Type) and Gel (Color). Omit when the headers are field names."
    • 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. Required when dry_run is False."
    • addedInput schema / properties / dry_run / description
      Added value: +"True (default) changes nothing and returns the plan to show the user; False applies it and then needs `document`."
    • addedInput schema / properties / key / description
      Added value: +"Which column(s) identify the device each row belongs to: \"channel\" (default, the Channel column), \"unit_number\" (only when unit numbers are unique in the whole plot) or \"position+unit_number\" (Position and Unit Number columns together; unit numbers repeat per position)."
    • addedInput schema / properties / path / description
      Added value: +"Path on this Mac to a .csv or .tsv exported from the spreadsheet; the first row holds the column headers."
  2. Added

TDQS

A4.1/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, and the description is consistent with that, adding substantial context: dry_run gates all writes, applying is all-or-nothing through vw_set_lighting_device_fields, a multi-match or no-match row aborts everything, and Spotlight overrides surface in `not_applied`. That is well beyond the annotations. It stops short of stating permission/auth requirements or row/volume limits, which would be the remaining behavioral gaps for a bulk mutation.

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-loads the two-phase workflow before the mechanics, and each sentence carries operational content rather than filler. The prose is dense and the return-shape sentence is a long parenthesis-heavy clause, but nothing is wasted.

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?

There is no output schema, and the description compensates by enumerating the dry-run return keys and the applied `result` fields, so an agent knows what comes back. Combined with atomicity, revert path, and column-matching rules, this is close to complete for a five-parameter bulk import; only permission or size constraints are unstated.

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%, so all five parameters including the `key` enum and `column_map` already carry descriptions, establishing a baseline of 3. The description reinforces matching semantics ('Each row is matched to exactly one device by `key`') and the write policy for empty cells and unknown headers, but adds little that the schema does not already say.

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?

Names a specific verb and resource ('Load a channel hookup or instrument schedule from a spreadsheet export into the Lighting Devices') and immediately frames the two-phase dry-run/apply model. An agent can distinguish this bulk-import tool from vw_set_lighting_device_fields and vw_insert_lighting_devices without opening a 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?

Gives explicit routing: dry run first, then one revertible apply step; 'For a handful of edits call vw_set_lighting_device_fields directly' names the alternative and the condition that selects it. It also names vw_revert_last as the undo path and vw_switch_document as a prerequisite.

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