Find the nearest elements to a reference element
find_nearestLocate the elements physically closest to a reference BIM element by 3D bounding-box distance, optionally filtered by category or level, and return their IDs for highlighting or zooming.
Instructions
Find the elements physically closest to a reference element.
Use this to answer proximity questions (e.g. "what's the nearest transformer to this panel?", "which air terminals are closest to the cooling tower?"), then pass the returned external_ids to highlight_elements or zoom_to. This tool does NOT change the view by itself.
Distance is the true 3D gap between bounding boxes in feet: 0 means the elements overlap or touch, and elements on different floors are correctly far apart.
Examples: - Nearest transformer to a panel: reference_external_id=, category='transformers' - Five closest anything: reference_external_id=, limit=5
Returns: {"reference_external_id": str, "count": int, "elements": [{external_id, asset_type, description, level_name, distance_ft}]} ordered nearest first.
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": {
"reference_external_id": "<reference_external_id>"
},
"name": "find_nearest"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | Optional building level to restrict the neighbors to. Omit for all levels. | |
| limit | No | How many of the closest elements to return (1-50). | |
| category | No | Optional category to restrict the neighbors to (e.g. the nearest transformer). Omit to consider all tracked assets. | |
| reference_external_id | Yes | The externalId of the element to measure from (e.g. the panel or AHU the question is about). Get it from find_by_category or find_elements first. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||