Tools: Zone Properties¶

@tool(annotations=_READ_ONLY)
def get_zone_properties(
    zone_name: Annotated[str | None, Field(description="Zone name. Omit for all zones.")] = None,
) -> GetZonePropertiesResult:
    """Typed summary of zone geometry, surfaces, constructions, schedules, and HVAC.

    Returns floor area, volume, ceiling height, surface counts by type (walls/floors/roofs/
    windows/doors), unique construction names, schedule names referenced by zone loads,
    HVAC equipment connection names, and thermostat control object names.

    Geometry values (area, volume, height) are calculated from BuildingSurface:Detailed
    vertices and returned as None when no surfaces exist for the zone.

    Preconditions: model loaded.
    Side effects: none — read-only.
    """
    state = get_state()
    doc = state.require_model()

    if zone_name is not None:
        if "Zone" not in doc or doc.get_collection("Zone").get(zone_name) is None:
            from fastmcp.exceptions import ToolError

            raise ToolError(f"Zone '{zone_name}' not found in the model.")
        zones = [_build_zone_properties(doc, zone_name)]
    else:
        if "Zone" not in doc:
            return GetZonePropertiesResult(zone_count=0, zones=[])
        zones = [_build_zone_properties(doc, z.name) for z in doc.get_collection("Zone")]

    logger.debug("get_zone_properties: returned %d zone(s)", len(zones))
    return GetZonePropertiesResult(zone_count=len(zones), zones=zones)