Skip to main content
Glama

Read reference drawing

read_reference
Read-onlyIdempotent

Drawings and point clouds uploaded to the room, shared by all its models. Without id: the list - id, name, format, status ready|waiting, stand, readable (false: viewer only); a sheet adds scale, PDF page, n_pages. With id: nodes per layer in drawing units (source file), frame {origin, x, y, z} in project m: point (a, b, c) = origin + ax + by + c*z, flat nodes at flat_z. A sheet: PDF nodes in pt, PNG or JPEG one image node {width, height} in px, no pixels; origin bottom left, y up; only its scale makes m (unit.factor_m; unit.scale rule named, or pairs | fit_model_extent: assumptions). A WGS84 GeoJSON reads in map m of the model CRS, never degrees (coordinates {kind map, crs_name}, source assumption with projection rule and delta_m), within and pages too; without a georeference REFERENCE_GEOREF_REQUIRED. A point cloud: a summary, never a point, its bounds_m to hold against the model; probe {box, yaw_deg} (project m): n_points, heights, planes with rms_m; compare {guids}: per element the distance of the points nearest it, which body took the rest, how much of its free faces they cover; get_guide point_cloud. trust holds: the frame is where it lies now; uncertain: the place is assumed (source names the rule) - only a place the person confirmed or placed by a georef stamped user holds, a measured scale (drawing_pair_scale) never; void: unit or placement missing, no frame, place_reference gives them. Check an uncertain frame against points you know before building on it. coverage: what the file held and was read (n_not_projected: nodes left out whole); a node over a page is summarized, never cut. layers, within, elements narrow the nodes; over 2000 without them: no nodes, an overview with extent per layer and a try. next carries stand and revision: a page after a placement or model change is refused. A line is no wall and a rectangle no opening: say what you read it as. get_selection names points picked on a reference (drawing.at), one selected whole, and objects picked in it (drawing_elements: their keys go to elements). Read-only.

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": "read_reference"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNoA reference id from the list: its nodes and frame; without id the list
limitNoNodes per answer, default 100; next names the rest
probeNoA point cloud only: n_points, heights, a plane over all its points in the box and the dominant plane with its inliers, never the points
standNoThe stand of the list or of next; a page after the placement changed is refused (place_moved)
layersNoOnly nodes on these layers, names as the reference lists them
offsetNoFirst node; default 0
withinNoOnly nodes whose extent meets the box [x0, y0, x1, y1], in the units of the nodes (WGS84 GeoJSON: map m)
compareNoA point cloud only: how far its points lie from these elements, each point counted once for the body nearest it
elementsNoOnly the nodes of these objects, keys as get_selection drawing_elements names them; an unknown key is refused
revisionNoThe revision of next; a page after the model moved to another revision is refused (revision_moved)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A3.8/5.0
Behavior4/5

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

The annotations already cover read-only, idempotent and non-destructive semantics, yet the description adds substantial behaviour: refusal conditions ("a page after a placement or model change is refused", place_moved/revision_moved), an error state (REFERENCE_GEOREF_REQUIRED), a node cap and overview fallback, and the fact that "a node over a page is summarized, never cut" and that bitmaps carry "no pixels". Those are exactly the beyond-annotation facts an agent needs. Some disclosures are so compressed ("trust holds: the frame is where it lies now") that the behaviour is stated but hard to parse reliably.

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

Conciseness2/5

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

The content is front-loaded correctly, but the prose is telegraphic to the point of being unreadable: articles and verbs are dropped, and semicolon-chained clauses pack units, coordinate math, trust states and refusals into single sentences. Nearly every clause is information-bearing, yet the packing costs comprehension and forces re-reading. It is over-dense rather than over-long.

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?

With 10 parameters, nested probe/compare objects and no output schema, the description carries the return-value burden and does so: it enumerates list fields (id, name, format, status, stand, readable), sheet extras, per-layer nodes with the frame transform, point-cloud probe and compare outputs, and coverage reporting. For a tool of this complexity that is close to complete, though the trust/uncertain/void vocabulary is introduced without definition of what an agent should do with each except via one sentence.

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; the description earns an extra point by grouping parameters functionally ("layers, within, elements narrow the nodes") and crossing schemas ("elements: their keys go to elements" from get_selection, "stand and revision" pairing with next). It also explains that omitting id switches the tool into list mode, which reframes what a missing parameter means. It still does not explain limit/offset interaction beyond the schema's own text.

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?

The opening states the resource concretely ("Drawings and point clouds uploaded to the room, shared by all its models") and then splits behaviour by argument presence: "Without id: the list ... With id: nodes per layer in drawing units". That split lets an agent distinguish a listing call from a content call without opening the schema. The verb itself is never stated plainly ("read" only appears in the name/annotation title), and the dense, article-free phrasing obscures the purpose for a first-time reader.

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?

Several concrete routing and precondition rules are given: "void: unit or placement missing, no frame, place_reference gives them", "get_guide point_cloud", and "Check an uncertain frame against points you know before building on it". It also explains the fallback when the payload is large ("over 2000 without them: no nodes, an overview with extent per layer and a try"). There is no explicit when-not / use-X-instead statement for the common case, so guidance is strong but incomplete.

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