ifcquery, ifcmcp: better bot selector syntax hints

brunopostle · brunopostle · commit 002b7c5d6ee9 · 2026-04-10T22:09:56.000+01:00
diff --git a/src/ifcmcp/ifcmcp/core.py b/src/ifcmcp/ifcmcp/core.py
@@ -278,7 +278,12 @@ def ifc_info(self, element_id: int) -> dict[str, Any]:
         return info.info(model, element)
 
     def ifc_select(self, query: str) -> list[dict[str, Any]]:
-        """Filter elements using ifcopenshell selector syntax (e.g. 'IfcWall', 'IfcWindow')."""
+        """Filter elements using ifcopenshell selector syntax.
+
+        Examples: ``IfcWall``, ``IfcWall, IfcColumn``, ``! IfcWall``,
+        ``IfcWall, Name = "My Wall"``, ``type = "Concrete Wall"``,
+        ``material = "Concrete"``.
+        """
         return select.select(self._require_model(), query)
 
     def ifc_relations(self, element_id: int, traverse: str = "") -> dict[str, Any] | list[dict[str, Any]]:
@@ -536,7 +541,12 @@ def openai_tools(self) -> list[dict[str, Any]]:
             {
                 "type": "function",
                 "name": "ifc_select",
-                "description": "Select elements using ifcopenshell selector syntax (e.g. 'IfcWall').",
+                "description": (
+                    "Select elements using ifcopenshell selector syntax. "
+                    "Examples: 'IfcWall', 'IfcWall, IfcColumn', '! IfcWall', "
+                    "'IfcWall, Name = \"My Wall\"', 'type = \"Concrete Wall\"', "
+                    "'material = \"Concrete\"'."
+                ),
                 "parameters": {
                     "type": "object",
                     "properties": {"query": {"type": "string"}},
diff --git a/src/ifcquery/ifcquery/select.py b/src/ifcquery/ifcquery/select.py
@@ -26,7 +26,16 @@
 
 
 def select(model: ifcopenshell.file, query: str) -> list[dict[str, Any]]:
-    """Filter elements using selector syntax and return matching element summaries."""
+    """Filter elements using ifcopenshell selector syntax and return matching element summaries.
+
+    Examples:
+    - ``IfcWall`` — all walls
+    - ``IfcWall, IfcColumn`` — walls and columns
+    - ``! IfcWall`` — everything except walls
+    - ``IfcWall, Name = "My Wall"`` — walls with a specific name attribute
+    - ``type = "Concrete Wall"`` — elements assigned that type product
+    - ``material = "Concrete"`` — elements with that material
+    """
     elements = ifcopenshell.util.selector.filter_elements(model, query)
     results = []
     for element in sorted(elements, key=lambda e: e.id()):
