From 002b7c5d6ee97075eff7e46106c27c8ae0551a4f Mon Sep 17 00:00:00 2001
From: Bruno Postle <bruno@postle.net>
Date: Fri, 10 Apr 2026 22:09:56 +0100
Subject: [PATCH] ifcquery, ifcmcp: better bot selector syntax hints

---
 src/ifcmcp/ifcmcp/core.py       | 14 ++++++++++++--
 src/ifcquery/ifcquery/select.py | 11 ++++++++++-
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/src/ifcmcp/ifcmcp/core.py b/src/ifcmcp/ifcmcp/core.py
index ed9f91c3c9..137cdbdce0 100644
--- a/src/ifcmcp/ifcmcp/core.py
+++ b/src/ifcmcp/ifcmcp/core.py
@@ -278,7 +278,12 @@ class IfcSession:
         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 @@ class IfcSession:
             {
                 "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
index c28a159b90..f3ee1dceaa 100644
--- a/src/ifcquery/ifcquery/select.py
+++ b/src/ifcquery/ifcquery/select.py
@@ -26,7 +26,16 @@ import ifcopenshell.util.selector
 
 
 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()):