Skip to main content
Glama
Vectorworks MCP

Vectorworks MCP

vw_insert_hoists

Places Spotlight hoists at specified points using an existing hoist symbol, setting capacity, chain, motor, and ID data in one revertible all-or-nothing step.

Instructions

Place Spotlight hoists (BrxHoist plug-in objects) at points, one revertible step. Each hoist gets the symbol's capacity, chain weight and length, motor weight, voltage, speed and motor height (from the symbol's HoistObjectData, as the Hoist tool does), its ID, location, function, direction and hook height. Linking to a truss system is left to Vectorworks' own hoist tools. All-or-nothing; vw_revert_last removes every hoist placed. Returns {symbol, count, hoists: [{uuid, id, x, y}], class?}; the derived values (hook height, chain length, weight) exist after the regeneration: read them with vw_list_hoists.

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": {
      "symbol": "<symbol>",
      "points": "<points>",
      "height": "<height>"
    },
    "name": "vw_insert_hoists"
  }
}

Input Schema

NameRequiredDescriptionDefault
idsNoHoist IDs, one per point, in order (motor numbers such as 'M1' or '1A'). Omitted: id_prefix plus 1, 2, 3 ...
layerNoDesign layer to place the new object(s) on, by name. Omitted: the user's active layer.
notesNoNotes field of every hoist.
heightYesHook height above the low point, as a dimension string: '12 m', '39'4"', '15000 mm', or a number in document units. Sets the hoist's hook-to-hook distance and chain length.
pointsYes[[x, y], ...] in document units: one hoist per point, usually on a truss run (vw_list_truss gives piece centres).
symbolYesName of a hoist symbol already in the document (vw_list_symbols), such as 'Dead Hang 1 Ton Audio' or a chain motor from the Rigging/Hoists libraries (vw_list_library, then vw_import_resource). It must carry a HoistObjectData record.
documentNoName of the document this call may change, as listed by vw_list_documents. If given and another document is in front, nothing changes and the call fails; use vw_switch_document first. Always pass it for writes.
functionNoWhat the hoist carries: Lights, Audio, Video, Scenery, Other. Omitted: the symbol's own function.
locationNoLocation text shown in the hoist's data (the truss or position it picks up, such as 'US TRUSS'). Omitted: blank.
hoist_posNo'up' (default): motor at the top, the usual chain hoist; 'down': motor climbs, hangs from the load.up
id_prefixNoPrefix for automatic hoist IDs when ids is omitted.M
class_nameNoClass to assign to the new object(s), by name; it must exist (vw_create_class or vw_apply_class_standard first). Applied in a second job after the insert. Omitted: the user's active class.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.2.0

TDQS

A4.9/5.0
Behavior5/5

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

Goes well past the annotations by disclosing atomicity ('All-or-nothing'), the exact consequence of reverting ('vw_revert_last removes every hoist placed'), and a non-obvious sequencing trap: derived values (hook height, chain length, weight) only exist after regeneration and must be read via vw_list_hoists. It also enumerates the returned shape, compensating for the absent output schema.

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-loaded with the action, then behaviour, then return shape and follow-up tool. Despite being a dense paragraph, every clause carries operational information (atomicity, revert scope, regeneration timing) with no filler.

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 12-parameter write tool with no output schema, the description covers what is created, what is deliberately left out, how failure/atomicity behaves, what is returned, and when derived values become readable. Nothing an agent needs to invoke it correctly 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 schema already carries per-parameter meaning and the baseline is 3. The description still adds value by tying the parameters to domain semantics: which values are inherited from the symbol's HoistObjectData versus supplied per call (ID, location, function, direction, hook height), and that height drives hook-to-hook distance and chain length.

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 ('Place Spotlight hoists (BrxHoist plug-in objects) at points') and immediately scopes what the tool does and does not do, noting that truss-system linking is left to Vectorworks' own hoist tools. An agent can distinguish this from vw_insert_symbol or vw_insert_truss_run 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?

Gives explicit when-to-use context (one hoist per point, usually on a truss run with centres from vw_list_truss), an explicit exclusion (truss linking is not handled here), and routes to alternatives for adjacent jobs: vw_revert_last to undo, vw_list_hoists to read derived values, vw_list_symbols/vw_import_resource to source the symbol. Little is left to inference.

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