Archicad-MCP

Overview Schema Source Related Servers Discussions Admin

Create Swept Beam

create_swept_beam

Destructive

Places a sloped or curved Swept Beam along a Morph line, polyline, arc, or XYZ points, with a Profile Manager or rectangular profile. Runs as a dry-run first and reports warnings before placement.

Instructions

Place a Swept Beam: a sloped, curved beam with a Profile Manager profile or a rectangle, as the 'Swept Beam' library part. The path comes from source_guid (a Morph line, Polyline, Line or Arc) or from points [{x, y, z}] in metres. Flat sources take start_height (metres above the source) and slope_percent; morph lines and points keep their own heights. profile is {"attribute": ""} or {"rectangle": {"width", "height", "building_material"}} (default 0.2 x 0.2 rectangle). update_guid rewrites the path of an existing Swept Beam, keeping its GUID; its profile, offsets, flip and end cuts stay unless given, its segment profiles stay while the node count does, and node roll resets to 0. End cuts in degrees: cut_start_plan and cut_end_plan turn a cut counter-clockwise from square in plan (-80 to 80); cut_start_tilt and cut_end_tilt lean the top of the face out past the end (-85 to 85, 0 is square to the beam, the beam's slope there gives a vertical face). ref_line ('left face', 'centre', 'right face', looking from the first point to the last) puts that face of the beam on the path; ref_offset (metres) moves the beam that far away from it (with centre, to the right). DRY-RUN BY DEFAULT: reports nodes, arcs, the maximum deviation from the source and warnings. Pass dry_run=false to place or update.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "create_swept_beam"
  }
}

Input Schema

Name	Required	Description	Default
`flip`	No
`port`	No
`points`	No
`dry_run`	No
`profile`	No
`offset_u`	No
`offset_w`	No
`ref_line`	No
`ref_offset`	No
`source_guid`	No
`update_guid`	No
`cut_end_plan`	No
`cut_end_tilt`	No
`start_height`	No
`slope_percent`	No
`cut_start_plan`	No
`cut_start_tilt`	No
`path_tolerance`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.7.1Oct 1, 2026

TDQS

A4.2/5.0

Behavior5/5

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

Goes well beyond the annotations: discloses that it is dry-run by default and only writes when dry_run=false, that update_guid preserves GUID/profile/offsets/flip/end cuts and resets node roll, the numeric ranges for cut angles, and what the dry-run report contains. That is exactly the extra behavioral context the destructiveHint alone cannot 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?

Front-loaded with the purpose, and nearly every sentence adds real information (sources, profile default, update preservation rules, dry-run). However it is a single dense paragraph with no bullets or breaks, and the end-cut sentence is hard to parse on first read.

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?

An output schema exists, so return-value explanation is rightly omitted, and the dry-run report contents plus safety profile are covered. For an 18-parameter geometry tool it is close to complete, with only port, path_tolerance and offset_u/offset_w left undocumented anywhere.

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?

With 0% schema description coverage across 18 params, the description carries the burden and mostly delivers: it defines source_guid source types, points format and units, start_height/slope_percent applicability, the profile object shape and default, end-cut angles with ranges and direction, and ref_line/ref_offset semantics. Gaps remain: port, path_tolerance, and the directional meaning of offset_u/offset_w are never explained, and flip is only named in passing.

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?

Opens with a specific verb and resource: 'Place a Swept Beam: a sloped, curved beam with a Profile Manager profile or a rectangle, as the "Swept Beam" library part.' An agent knows exactly what is produced. It does not name a sibling (e.g. create_elements) for the generic case, so it stops short of explicit sibling differentiation.

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

Usage Guidelines4/5

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

Gives clear operational context: path comes from source_guid OR points, update_guid rewrites an existing beam instead of creating, and dry_run=true is the default. This tells the agent which mode to pick. No explicit 'use X tool instead when Y' routing against siblings, so not a 5.

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

Deploy Server