Skip to main content
Glama

Place reference drawing

place_reference

Places a reference drawing of the room (listed by read_reference): named by id and the stand you read, one change per call. DXF or a sheet (PDF, PNG, JPEG); a GeoJSON lies through the georeference of the model. A sheet takes no unit and no georef; align: pair 0-1 measures its scale (an assumption) unless a person named one; alignment.scale says which, check tests it; a drawing point off the sheet is refused. unit: the drawing unit, where the file names none or a wrong one (a new unit drops an alignment: aligned_dropped). elevation_m or storey: the height of the reference. height_mode flat: everything lies at that height; file: the own z of 3D content plus that height (terrain with absolute heights of 400 m beside a model at 0: file with elevation_m -400). file is refused where all content is flat, flat at a point cloud; unnamed, the content decides (mostly 3D: file). mode origin: drawing zero on the project origin; georef: drawing coordinates as map coordinates through the served model's georeference. align: two pairs {drawing, model} give a rigid move at the scale of the unit; check is a third pair the move does not use, far from the first: its residual shows a swapped pair or a pair on another reference. revert_last: the choice before the last one back, exactly; once, then nothing_to_undo. Writes only the placement of the reference, never a model and never a revision (undo and restore_revision leave it); it holds for every model of the room (applies_to). Report: before and after, each with its stand (the next call names after.stand), changed, and for align the alignment with rotation_deg, the length deviations and check {residual_m, tolerance_m, within}. check within false stands at the top of the report: the placement is written anyway, as in the viewer, and a swapped pair or the wrong reference reads like this. A call that succeeds is not a job that's done: double-check the frame of read_reference against points you know, and revert_last where it does not hold.

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": {
      "id": "<id>",
      "stand": "<stand>"
    },
    "name": "place_reference"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesThe reference, its id from read_reference
modeNoorigin: drawing zero on the project origin; georef: drawing coordinates are map coordinates of the georeference
unitNoThe drawing unit
alignNoRigid move from two pairs, checked at a third
standYesThe stand read_reference or the last place_reference report named for it; another one now is refused (place_moved) and nothing is written
sourceNoWhere the change comes from: assumption (default, your own reading, stamped so in the reference; read_reference then reads the place uncertain) or user (only what the person named word for word)
storeyNoGlobalId of an IfcBuildingStorey of the served model: its height, as elevation_m
elevation_mNoHeight in project m, bound to no storey: flat content lies at it, in height_mode file the own z is added
height_modeNoflat: all content at the height; file: own z plus the height
revert_lastNoThe unit and placement before the last change back

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.1/5.0
Behavior5/5

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

Adds substantial behavior beyond the annotations: it writes only the placement, never a model or revision; undo and restore_revision do not affect it; it applies to every model of the room; revert_last works exactly once and then returns nothing_to_undo. It also discloses failure modes with named error codes (place_moved, revision_moved, nothing_to_undo, aligned_dropped) and states that a failed check still writes the placement. This is far richer than the readOnly/destructive/idempotent hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The size is defensible for 10 parameters, but the prose is a chain of semicolon-linked fragments that require re-reading (e.g. "file is refused where all content is flat, flat at a point cloud; unnamed, the content decides"). Key facts such as the report shape are packed into a dense final block rather than surfaced early. Little is pure filler, but structure is the weak point.

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?

For a 10-parameter mutating tool with nested objects and no output schema, the description covers nearly everything an agent needs: what is mutated, what is preserved, error codes, revert semantics, and the shape of the returned report including check {residual_m, tolerance_m, within}. Gaps are minor – a few undefined terms and no explicit statement of what happens when id or stand resolve ambiguously beyond the naming error codes.

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 baseline is 3, but the description adds semantics the schema does not carry: a unit change drops an alignment, height_mode=file vs flat with a concrete terrain example, the purpose of the third align pair (detecting a swapped or wrong-reference pair), and when mode origin vs georef applies. It leaves some phrases under-explained (applies_to, what 'stand' means operationally), so it is strong but not exhaustive.

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?

States a specific verb and resource: "Places a reference drawing of the room", and anchors it to the sibling that lists references (read_reference), plus the identifying pair (id and stand). An agent can tell this apart from read_reference and from model-editing siblings. Clarity is degraded by the telegraphic, jargon-heavy register, but the core purpose is unambiguous.

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 real operating guidance: one change per call, names must come from read_reference or the last report, revert_last is the recovery path, and it explicitly instructs double-checking the frame and reverting where it does not hold. It also distinguishes source=assumption vs user by who supplied the value. It stops short of a full when-not-to-use list, but the routing and recovery conditions are clear.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources