hcl-mcp

Overview Schema Source Related Servers Discussions Admin

import_geometry

Import a Wavefront OBJ room into a Radiance scene, mapping materials per group and optionally deriving sensors for daylight and electric lighting analysis.

Instructions

Import a Wavefront .obj room into a per-channel Radiance scene (obj2rad -> xform).

material_map: {group_name: spec} keyed by OBJ usemtl (else g) names; unmapped groups hard-fail. spec is a library-name string (illustrative reflectance) or a dict {"type": "plastic"|"glass"|"ground"|"context"|"luminaire"|"floor", "refl"/"tvis": float, ...}: plastic=opaque diffuse; glass=transmitting; ground=opaque + drives ground_albedo; context=exterior shading (in oconv, excluded from sensor footprint/room-sanity); luminaire=marker + IES (-> electric_lights); floor=opaque + anchors the sensor footprint. units: mm|cm|m|ft. up_axis: Y|Z.

v2/v3 parameters:

north_angle_deg: clockwise azimuth (degrees) that post-remap +Y points toward; applied as -rz(-north) after up-axis correction.
dry_run=True: return a discovery payload (groups, bbox_m, mesh_quality, suggestions) without binding materials or running Radiance. material_map not required in dry_run mode.
sidecar: path to a JSON file supplying defaults (explicit kwargs always win over sidecar).
derive_sensors: derive a work-plane grid + eye-level observer_sets (at BOTH seated 1.2 m and standing 1.6 m by default) + DGP-view strings from the geometry.
eye_heights / workplane_h / spacing: tune the derived-sensor layout (defaults (1.2, 1.6) / 0.8 / 0.6).
annotate: build a colored-by-material falsecolor render (oconv -> rpict -> falsecolor; live-validated).
strict: raise GeometryHealthError when the embedded health report (result["health"]) holds error-severity findings (e.g. coincident surfaces), instead of returning a report that looks plausible but is built on defective geometry. strict has NO effect when dry_run=True: the dry_run path returns before materials are bound, so no health report is computed to raise on.

Returns geometry_set + material_sets (index-aligned per channel-set) to compose into run_grid / run_annual scene_sets, plus discovered groups and warnings, an always-present apertures report, and a provenance manifest (written as a manifest.json sidecar -> manifest_path, and embedded as a #-comment header in each geometry .rad). Conditional keys appear only when their feature is mapped/requested: ground_albedo/ground_albedo_kind (a 1-nm albedo from any type:"ground" group -> feed to spectral_sky_from_epw(spectral_albedo=...)); electric_lights (drop-in luminaire payload for run_grid/run_image, which run ies2rad + colorize); context_groups (type:"context" exterior-shading groups); and grid_points/observer_sets/observer_points/glare_views (derive_sensors).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`run`	No
`units`	No
`strict`	No
`dry_run`	No
`sidecar`	No
`spacing`	No
`up_axis`	No
`annotate`	No
`obj_path`	Yes
`work_dir`	No
`eye_heights`	No
`workplane_h`	No
`channel_type`	No
`material_map`	No
`derive_sensors`	No
`north_angle_deg`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 9, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations are absent, so the description carries the full burden, and it delivers: unmapped groups 'hard-fail', dry_run 'return[s] a discovery payload ... without binding materials or running Radiance', strict raises GeometryHealthError on error-severity findings, and it explicitly flags the subtle interaction that 'strict has NO effect when dry_run=True'. It also discloses conditional keys appearing only when requested, the manifest sidecar write, and live-validation for annotate. This is exceptional disclosure, including an edge-case interaction most tools omit.

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?

The description is long, but the length is earned given 16 params, 0% schema coverage, and no annotations. The core purpose is front-loaded, parameters are grouped under a 'v2/v3' section, and return/conditional keys are clearly enumerated. The material_map specification is a dense run-on paragraph that is harder to parse than the rest, but every sentence carries information; no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists and the description still details returns (geometry_set, material_sets, apertures, manifest, conditional keys), which is thorough. But for a 16-param tool it leaves run, work_dir, and channel_type completely unexplained, and it gives no guidance for distinguishing from closely-related siblings like check_geometry or preview_scene. Those gaps keep it from being complete despite the strong behavioral and parameter coverage.

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 0%, so the description must compensate, and it does heavily: it adds enum-like values (units: mm|cm|m|ft; up_axis: Y|Z), fully specifies material_map's keying and every type-dict (plastic/glass/ground/context/luminaire/floor), and explains north_angle_deg (applied as -rz(-north)), sidecar precedence ('explicit kwargs always win'), and defaults for eye_heights/workplane_h/spacing. The gap: three params — run, work_dir, and channel_type — are never mentioned, leaving their semantics entirely unexplained in both schema and description.

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?

Opens with a specific verb+resource+destination: 'Import a Wavefront .obj room into a per-channel Radiance scene (obj2rad -> xform)'. This is unmistakable against siblings like run_grid/run_image (simulation runners), check_geometry, and preview_scene. The derived-sensor outputs (grid_points/observer_sets) could be mistaken for the workplane_grid/observer_points siblings, but the description clearly frames these as outputs of this import tool rather than the tool's purpose.

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 strong pipeline context: returned scene_sets are 'to compose into run_grid / run_annual', luminaire payload is 'drop-in ... for run_grid/run_image', and ground_albedo is meant to 'feed to spectral_sky_from_epw'. It also explains dry_run's discovery role. However, it never explicitly states when NOT to use it or names an alternative for a given condition, so the when-vs-other guidance is implicit through workflow positioning rather than direct exclusion.

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