pi-revit 0.3.1 → 0.5.0

package/src/Revit/Tools/ExecuteCsharp.cs

@@ -20,11 +20,12 @@ namespace RevitBridge.Tools
     /// </summary>
     public sealed class ScriptGlobals
     {
-        internal ScriptGlobals(Document document, UIDocument uiDocument, UIApplication uiApplication, Action<object?> dump)
+        internal ScriptGlobals(Document document, UIDocument uiDocument, UIApplication uiApplication, JsonElement inputValues, Action<object?> dump)
         {
             doc = document;
             uidoc = uiDocument;
             uiapp = uiApplication;
+            inputs = inputValues;
             Dump = dump;
         }
 
@@ -37,6 +38,9 @@ namespace RevitBridge.Tools
         /// <summary>The Revit UI application.</summary>
         public UIApplication uiapp { get; }
 
+        /// <summary>Structured inputs supplied separately from the script source.</summary>
+        public JsonElement inputs { get; }
+
         /// <summary>Records a value into the result's dumps[] (safely projected at call time).</summary>
         public Action<object?> Dump { get; }
     }
@@ -58,9 +62,19 @@ namespace RevitBridge.Tools
         private const int MaxReportedErrors = 20;
 
         public string Name => "execute_csharp";
+        public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+        public IReadOnlyList<string> Keywords => new[] { "script", "code", "csharp", "c#", "custom", "automation", "macro" };
+        public IReadOnlyList<ToolLimit> Limits => new[]
+        {
+            new ToolLimit("Automatic preview or rollback of custom code", "tool", "dedicated tools with preview (set_parameters, transform_elements, delete_elements, manage_views, ...)"),
+            new ToolLimit("Undoing file, UI or external effects on rollback", "user", "Inspect and clean up those effects explicitly"),
+            new ToolLimit("Saving the model", "user", "Save only when the user asks"),
+        };
+        public string? Verification => "reread";
         public string Label => "Execute C#";
-        public string Description => "Compile and run a C# script on the Revit API thread against the open model — the escape hatch for anything without a dedicated tool: element creation, deletion, geometry edits (move/copy/rotate), views, sheets, schedules, tagging, families, links, worksets. Globals: doc (Document), uidoc (UIDocument), uiapp (UIApplication), and Dump(value) to record intermediate values into the result's dumps[]. Default imports: System, System.Linq, System.Collections.Generic, Autodesk.Revit.DB, Autodesk.Revit.UI — add using directives at the top for sub-namespaces (e.g. using Autodesk.Revit.DB.Architecture;). The entire run is wrapped in ONE transaction named 'execute_csharp': committed on success; on failure rollback is attempted and its confirmed status is reported (do not open your own Transaction; sub-transactions are fine). The script's final expression or return statement becomes returnValue; return primitives, strings, or anonymous objects/lists — Revit API values are projected to safe shapes (Element -> {id,name,category,typeName,levelId}, ElementId -> number, XYZ -> {x,y,z}, Parameter -> {name,value,displayValue}; other API objects become strings) with depth and item caps, so never rely on raw API objects round-tripping. Lengths are in internal units (decimal feet) — convert with UnitUtils. Prefer collector-level filtering (FilteredElementCollector .OfCategory/.OfClass/.WhereElementIsNotElementType) and bounded loops: the call budget is 120s and Revit cannot be interrupted mid-script. Scripts must be fully synchronous — await/async is rejected at compile time, and blocking on tasks (Task.Result/.Wait()) can freeze Revit. Modal dialogs raised while running are auto-dismissed and reported in suppressedDialogs — unrecognized dialogs are answered dismissively (Cancel/Close/No) rather than confirmed, so an operation that raises a confirmation prompt may be cancelled; check suppressedDialogs when a result looks incomplete. Verify unfamiliar signatures with search_api_docs first.";
+        public string Description => "Compile and run a C# script on the Revit API thread against the open model, for operations that no dedicated tool covers. Specialist tools start inactive, so resolve the capability with find_revit_tools first and follow a tool's declared limits and alternatives. Globals: doc (Document), uidoc (UIDocument), uiapp (UIApplication), inputs (System.Text.Json.JsonElement, defaults to an empty object), and Dump(value) to record intermediate values into the result's dumps[]. Default imports: System, System.Linq, System.Collections.Generic, Autodesk.Revit.DB, Autodesk.Revit.UI — add using directives at the top for sub-namespaces (e.g. using Autodesk.Revit.DB.Architecture;). The entire run is wrapped in ONE transaction named 'execute_csharp': committed on success; on failure rollback is attempted and its confirmed status is reported (do not open your own Transaction; sub-transactions are fine). The script's final expression or return statement becomes returnValue; return primitives, strings, or anonymous objects/lists — Revit API values are projected to safe shapes (Element -> {id,name,category,typeName,levelId}, ElementId -> number, XYZ -> {x,y,z}, Parameter -> {name,value,displayValue}; other API objects become strings) with depth and item caps, so never rely on raw API objects round-tripping. Lengths are in internal units (decimal feet) — convert with UnitUtils. Prefer collector-level filtering (FilteredElementCollector .OfCategory/.OfClass/.WhereElementIsNotElementType) and bounded loops: the call budget is 120s and Revit cannot be interrupted mid-script. Scripts must be fully synchronous — await/async is rejected at compile time, and blocking on tasks (Task.Result/.Wait()) can freeze Revit. Modal dialogs raised while running are auto-dismissed and reported in suppressedDialogs — unrecognized dialogs are answered dismissively (Cancel/Close/No) rather than confirmed, so an operation that raises a confirmation prompt may be cancelled; check suppressedDialogs when a result looks incomplete. Verify unfamiliar signatures with search_api_docs first.";
         public bool Write => true;
+        public IReadOnlyList<string> Effects => new[] { "model", "ui", "files", "external" };
 
         public object ParametersSchema => new
         {
@@ -70,8 +84,9 @@ namespace RevitBridge.Tools
                 code = new
                 {
                     type = "string",
-                    description = "C# script body (top-level statements; using directives allowed at the top). Globals doc/uidoc/uiapp and Dump(value) are in scope. The final expression or a return statement is the result.",
+                    description = "C# script body (top-level statements; using directives allowed at the top). Globals doc/uidoc/uiapp/inputs and Dump(value) are in scope. The final expression or a return statement is the result.",
                 },
+                inputs = new { type = "object", description = "Optional structured JSON inputs, available as the inputs JsonElement global. Default empty object. Values are never interpolated into source code." },
                 expected_document = new
                 {
                     type = "string",
@@ -81,10 +96,10 @@ namespace RevitBridge.Tools
             required = new[] { "code" },
         };
 
-        public string? PromptSnippet => "Run a C# script against the Revit API inside one transaction (globals doc/uidoc/uiapp, Dump helper) — the escape hatch for operations without a dedicated tool.";
+        public string? PromptSnippet => "Run a C# script against the Revit API inside one transaction (globals doc/uidoc/uiapp, Dump helper) for operations no dedicated tool covers (check find_revit_tools first).";
         public IReadOnlyList<string>? PromptGuidelines => new[]
         {
-            "Use execute_csharp for Revit operations no dedicated tool covers (creation, deletion, geometry edits, views/sheets, tagging, ...); check exact signatures with search_api_docs before writing the script.",
+            "Use execute_csharp only when no dedicated tool covers the operation (check find_revit_tools and the tool's declared limits first); verify exact signatures with search_api_docs before writing the script.",
             "execute_csharp scripts must be fully synchronous (await/async is rejected; never block on Task.Result/.Wait()) and should return primitives or anonymous objects/lists, using Dump(...) for intermediates — raw Revit objects are projected to compact summaries; keep loops bounded and filter at the collector level.",
         };
 
@@ -98,6 +113,9 @@ namespace RevitBridge.Tools
             string code = JsonArgs.GetString(args, "code") ?? string.Empty;
             if (string.IsNullOrWhiteSpace(code))
                 throw new ArgumentException("code must be a non-empty C# script.");
+            var inputValues = args.TryGetProperty("inputs", out var suppliedInputs) ? suppliedInputs.Clone() : JsonSerializer.SerializeToElement(new { });
+            if (inputValues.ValueKind != JsonValueKind.Object) throw new ArgumentException("inputs must be a JSON object.");
+            if (inputValues.GetRawText().Length > 100000) throw new ArgumentException("inputs must not exceed 100,000 JSON characters.");
 
             var stopwatch = Stopwatch.StartNew();
 
@@ -109,7 +127,7 @@ namespace RevitBridge.Tools
             RejectAsyncCode(script.GetCompilation());
 
             var dumps = new List<object?>();
-            var globals = new ScriptGlobals(doc, uidoc, uiapp, value =>
+            var globals = new ScriptGlobals(doc, uidoc, uiapp, inputValues, value =>
             {
                 if (dumps.Count < MaxDumps)
                     dumps.Add(Project(value, 0));
@@ -195,6 +213,7 @@ namespace RevitBridge.Tools
                 typeof(Enumerable).Assembly,                                // System.Linq
                 typeof(Regex).Assembly,                                     // System.Text.RegularExpressions
                 typeof(Console).Assembly,                                   // System.Console
+                typeof(JsonElement).Assembly,                               // System.Text.Json
                 typeof(Document).Assembly,                                  // RevitAPI
                 typeof(UIApplication).Assembly)                             // RevitAPIUI
             .WithImports("System", "System.Linq", "System.Collections.Generic", "Autodesk.Revit.DB", "Autodesk.Revit.UI")
@@ -209,7 +228,7 @@ namespace RevitBridge.Tools
             });
             string more = errors.Count > MaxReportedErrors ? $"\n  … +{errors.Count - MaxReportedErrors} more error(s)" : string.Empty;
             return $"C# compilation failed with {errors.Count} error(s):\n{string.Join("\n", lines)}{more}\n"
-                + "Globals: doc, uidoc, uiapp, Dump(value). Default imports: System, System.Linq, System.Collections.Generic, "
+                + "Globals: doc, uidoc, uiapp, inputs (JsonElement), Dump(value). Default imports: System, System.Linq, System.Collections.Generic, "
                 + "Autodesk.Revit.DB, Autodesk.Revit.UI — add using directives for other namespaces.";
         }
 

package/src/Revit/Tools/ExportDocuments.cs

@@ -20,9 +20,18 @@ namespace RevitBridge.Tools
         private const int PngPixelWidth = 2048;
 
         public string Name => "export_documents";
+        public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+        public IReadOnlyList<string> Keywords => new[] { "pdf", "dwg", "ifc", "png", "print", "publish", "plot", "export sheets" };
+        public IReadOnlyList<ToolLimit> Limits => new[]
+        {
+            new ToolLimit("Formats other than PDF, DWG, PNG and IFC", "api", "Document.Export overloads (e.g. DXFExportOptions, NavisworksExportOptions); verify the installed exporter"),
+            new ToolLimit("Printing to a physical printer", "api", "PrintManager"),
+        };
+        public string? Verification => "inspect_output";
         public string Label => "Export Documents";
         public string Description => "Export documents from the open Revit model. format 'pdf'/'dwg'/'png' export the given sheet/view ids to files: pdf combines everything into one file by default (combine=false writes one PDF per sheet/view, named by Revit's naming rule); png renders 2048 px wide; ifc exports the whole model, or just what one given view shows. Files sort themselves per model: with output_dir omitted they land in Documents\\pi-revit\\Models\\<model title>--<identity hash>\\exports, derived from the document being exported (pass output_dir only for a different explicit target); file_name_prefix sets the base file name (default: the document title; Revit appends view/sheet suffixes for multi-file exports). Returns the produced file paths with sizes. Find sheet/view ids with get_elements (category 'Sheets' or 'Views') first.";
         public bool Write => true;
+        public IReadOnlyList<string> Effects => new[] { "model", "files" };
         public string Tier => "advanced";
 
         public object ParametersSchema => new

package/src/Revit/Tools/FailureGuard.cs

@@ -16,36 +16,36 @@ namespace RevitBridge.Tools
         public List<string> Warnings { get; } = new();
         public List<string> Errors { get; } = new();
 
-        public static FailureGuard Attach(Transaction transaction)
-        {
-            if (transaction.GetStatus() != TransactionStatus.Started)
-                throw new InvalidOperationException("FailureGuard must be attached after the transaction starts; Start resets failure handling options.");
-            var guard = new FailureGuard();
+        public static FailureGuard Attach(Transaction transaction)
+        {
+            if (transaction.GetStatus() != TransactionStatus.Started)
+                throw new InvalidOperationException("FailureGuard must be attached after the transaction starts; Start resets failure handling options.");
+            var guard = new FailureGuard();
             var options = transaction.GetFailureHandlingOptions();
             options.SetFailuresPreprocessor(guard);
             options.SetClearAfterRollback(true);
             transaction.SetFailureHandlingOptions(options);
-            return guard;
-        }
-
-        /// <summary>Best-effort cleanup that preserves the original failure and never
-        /// claims a rollback unless Revit confirms its final transaction status.</summary>
-        public static string RollBackAndDescribe(Transaction transaction)
-        {
-            try
-            {
-                if (transaction.GetStatus() == TransactionStatus.Started)
-                    transaction.RollBack();
-                var status = transaction.GetStatus();
-                return status == TransactionStatus.RolledBack
-                    ? "The transaction was rolled back; no changes from this transaction were saved."
-                    : $"Transaction status is {status}; rollback is not confirmed. Inspect Revit before retrying.";
-            }
-            catch (Exception ex)
-            {
-                return $"Rollback could not be confirmed ({ex.GetType().Name}: {ex.Message}). Inspect Revit before retrying.";
-            }
-        }
+            return guard;
+        }
+
+        /// <summary>Best-effort cleanup that preserves the original failure and never
+        /// claims a rollback unless Revit confirms its final transaction status.</summary>
+        public static string RollBackAndDescribe(Transaction transaction)
+        {
+            try
+            {
+                if (transaction.GetStatus() == TransactionStatus.Started)
+                    transaction.RollBack();
+                var status = transaction.GetStatus();
+                return status == TransactionStatus.RolledBack
+                    ? "The transaction was rolled back; no changes from this transaction were saved."
+                    : $"Transaction status is {status}; rollback is not confirmed. Inspect Revit before retrying.";
+            }
+            catch (Exception ex)
+            {
+                return $"Rollback could not be confirmed ({ex.GetType().Name}: {ex.Message}). Inspect Revit before retrying.";
+            }
+        }
 
         public FailureProcessingResult PreprocessFailures(FailuresAccessor accessor)
         {

package/src/Revit/Tools/GetElementDetails.cs

@@ -9,8 +9,16 @@ namespace RevitBridge.Tools
         private const int MaxIds = 50;
 
         public string Name => "get_element_details";
+        public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+        public IReadOnlyList<string> Keywords => new[] { "parameters", "properties", "inspect", "values", "material", "bounding box", "location" };
+        public IReadOnlyList<ToolLimit> Limits => new[]
+        {
+            new ToolLimit("Listing or filtering elements", "tool", "get_elements"),
+            new ToolLimit("Elements inside linked models", "tool", "get_linked_elements"),
+            new ToolLimit("Exact solid geometry or faces", "api", "Element.Geometry(Options)"),
+        };
         public string Label => "Get Element Details";
-        public string Description => "Inspect one or more elements by id: parameter VALUES (name, internal value, formatted displayValue, storage type, display unit where applicable, read-only/shared flags), plus optional type parameters, location (point/curve), bounding box, and materials. Internal numeric values are Revit internal units (feet-based); displayValue is formatted in the document's display units and 'unit' names that display unit. The single home for reading parameter values — get_elements only returns identity fields.";
+        public string Description => "Inspect one or more elements by id: parameter VALUES (name, internal value, formatted displayValue, storage type, display unit where applicable, read-only/shared flags), plus optional type parameters, location (point/curve), bounding box, and materials. Internal numeric values are Revit internal units (feet-based); displayValue is formatted in the document's display units and 'unit' names that display unit. Use get_elements parameter_names to project a small set of values alongside a query.";
 
         public object ParametersSchema => new
         {
@@ -167,7 +175,25 @@ namespace RevitBridge.Tools
             return total;
         }
 
-        private static Dictionary<string, object?> DescribeParameter(Document doc, Parameter parameter, string name, bool isType)
+        internal static IReadOnlyList<object> ProjectParameters(Document doc, Element element, IReadOnlyList<string> names, bool includeType)
+        {
+            var result = new List<object>();
+            void Project(Element source, bool isType)
+            {
+                foreach (string input in names.Distinct(StringComparer.OrdinalIgnoreCase))
+                {
+                    // Shared policy: projections report every match and flag ambiguity instead of choosing.
+                    var matches = ParameterResolver.FindAll(source, ParameterReference.Parse(input));
+                    var values = matches.Select(p => DescribeParameter(doc, p, p.Definition?.Name ?? "", isType)).ToArray();
+                    result.Add(new { requested = input, isType, found = values.Length > 0, ambiguous = values.Length > 1, matches = values });
+                }
+            }
+            Project(element, false);
+            if (includeType && doc.GetElement(element.GetTypeId()) is { } type) Project(type, true);
+            return result;
+        }
+
+        internal static Dictionary<string, object?> DescribeParameter(Document doc, Parameter parameter, string name, bool isType)
         {
             bool hasValue = parameter.HasValue;
             var row = new Dictionary<string, object?>

package/src/Revit/Tools/GetElementRelationships.cs

@@ -0,0 +1,82 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class GetElementRelationships : ITool
+{
+    public string Name => "get_element_relationships";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+    public IReadOnlyList<string> Keywords => new[] { "host", "hosted", "dependents", "nested", "group members", "joined", "relationship", "family hierarchy" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("A complete prediction of deletion effects", "tool", "delete_elements with preview"),
+    };
+    public string Label => "Get Element Relationships";
+    public string Tier => "advanced";
+    public string Description => "Inspect host-document element relationships: type, level, owning view, host, family parent/subcomponents, group or assembly membership, joined geometry and logical dependents. Dependents are not a complete deletion-impact prediction. Pagination applies independently to each relationship; links are not traversed.";
+    private static readonly string[] Kinds = { "type", "level", "owner_view", "host", "parent", "subcomponents", "group", "assembly", "members", "joined", "dependents" };
+    public object ParametersSchema => new
+    {
+        type = "object",
+        properties = new
+        {
+            element_id = new { type = "integer" },
+            relationships = new { type = "array", items = new { type = "string", @enum = Kinds } },
+            offset = new { type = "integer", minimum = 0 },
+            limit = new { type = "integer", minimum = 1, maximum = 200 },
+        },
+        required = new[] { "element_id" },
+    };
+
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        var id = JsonArgs.GetLong(args, "element_id") ?? throw new ArgumentException("element_id is required.");
+        var element = doc.GetElement(new ElementId(id)) ?? throw new ArgumentException("element_id does not exist in the active document.");
+        var kinds = (IReadOnlyList<string>?)JsonArgs.GetStringArray(args, "relationships") ?? Kinds;
+        if (kinds.Any(kind => !Kinds.Contains(kind))) throw new ArgumentException("Unknown relationship kind.");
+        int offset = Math.Max(0, JsonArgs.GetInt(args, "offset", 0));
+        int limit = Math.Clamp(JsonArgs.GetInt(args, "limit", 100), 1, 200);
+        var result = new Dictionary<string, object?>();
+        foreach (var kind in kinds.Distinct())
+        {
+            IEnumerable<ElementId> ids = kind switch
+            {
+                "type" => One(element.GetTypeId()),
+                "level" => One(element.LevelId),
+                "owner_view" => One(element.OwnerViewId),
+                "host" => One((element as FamilyInstance)?.Host?.Id),
+                "parent" => One((element as FamilyInstance)?.SuperComponent?.Id),
+                "subcomponents" => element is FamilyInstance family ? family.GetSubComponentIds() : Array.Empty<ElementId>(),
+                "group" => One(element.GroupId),
+                "assembly" => One(element.AssemblyInstanceId),
+                "members" => element is Group group ? group.GetMemberIds()
+                    : element is AssemblyInstance assembly ? assembly.GetMemberIds() : Array.Empty<ElementId>(),
+                "joined" => Joined(doc, element),
+                "dependents" => element.GetDependentElements(null),
+                _ => Array.Empty<ElementId>(),
+            };
+            var all = ids.Where(x => x != ElementId.InvalidElementId).DistinctBy(x => x.Value).OrderBy(x => x.Value).ToList();
+            var rows = all.Skip(offset).Take(limit).Select(x =>
+            {
+                var related = doc.GetElement(x);
+                return new { id = x.Value, name = related?.Name, category = related?.Category?.Name, unique_id = related?.UniqueId };
+            }).ToArray();
+            result[kind] = new { total_count = all.Count, returned_count = rows.Length, offset,
+                has_more = offset + rows.Length < all.Count,
+                next_offset = offset + rows.Length < all.Count ? (int?)(offset + rows.Length) : null, elements = rows };
+        }
+        return new { document_id = DocumentGuard.GetIdentity(doc), element_id = id, relationships = result };
+    }
+
+    private static IEnumerable<ElementId> One(ElementId? id)
+        => id == null || id == ElementId.InvalidElementId ? Array.Empty<ElementId>() : new[] { id };
+
+    private static IEnumerable<ElementId> Joined(Document doc, Element element)
+    {
+        // JoinGeometryUtils rejects family documents; surface that restriction explicitly.
+        if (doc.IsFamilyDocument) throw new ArgumentException("joined relationships require a project document. Request other relationship kinds for families.");
+        return JoinGeometryUtils.GetJoinedElements(doc, element);
+    }
+}

package/src/Revit/Tools/GetElementTypes.cs

@@ -9,6 +9,14 @@ namespace RevitBridge.Tools
         private const int MaxLimit = 1000;
 
         public string Name => "get_element_types";
+        public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+        public IReadOnlyList<string> Keywords => new[] { "types", "family types", "family symbols", "unused types", "loaded families", "purge candidates" };
+        public IReadOnlyList<ToolLimit> Limits => new[]
+        {
+            new ToolLimit("Creating or duplicating types", "api", "ElementType.Duplicate"),
+            new ToolLimit("Loading families", "api", "Document.LoadFamily"),
+            new ToolLimit("The types of the family being edited in a family document", "api", DocumentKind.FamilyApi),
+        };
         public string Label => "Get Element Types";
         public string Description => "List element types / family symbols (wall types, door types, ...) for a category or class: id, name, familyName, category, isFamilySymbol, optional placed-instance count per type (answers 'used vs merely loaded'). Use the ids with get_elements type_id or for type assignment.";
 

package/src/Revit/Tools/GetElements.cs

@@ -20,8 +20,16 @@ namespace RevitBridge.Tools
         private const double Epsilon = 1e-6;
 
         public string Name => "get_elements";
+        public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+        public IReadOnlyList<string> Keywords => new[] { "list", "find", "query", "count", "filter", "search elements", "how many" };
+        public IReadOnlyList<ToolLimit> Limits => new[]
+        {
+            new ToolLimit("Elements inside linked models", "tool", "get_linked_elements"),
+            new ToolLimit("Grouped counts or statistics over a whole scope", "tool", "summarize_elements"),
+            new ToolLimit("Spatial containment or intersection", "tool", "query_spatial_elements"),
+        };
         public string Label => "Get Elements";
-        public string Description => "Query Revit elements: scope by category (display name like 'Walls' or enum name like 'OST_Walls'), element class, level, type id, or active view; filter by parameter rules; paginate with offset/limit or just count with count_only. Returns identity fields only (id, name, category, typeName, levelId) — read parameter values with get_element_details. Rules with an explicit BuiltInParameter or shared GUID can evaluate inside Revit's collector; display-name rules, regex rules, and unsupported quick filters run as a per-element scan. A display name can identify different parameters even within one category or class. Scope queries to reduce the scan, or use an explicit parameter identity when appropriate. Numeric rule values are interpreted in the document's display units for that parameter unless 'unit' is given.";
+        public string Description => "Query Revit elements: scope by category (display name like 'Walls' or enum name like 'OST_Walls'), element class, level, type id, or active view; filter by parameter rules; paginate with offset/limit or just count with count_only. Returns identity fields and optional parameter_names projections; include_type_parameters also reads the requested values from each type. Rules with an explicit BuiltInParameter or shared GUID can evaluate inside Revit's collector; display-name rules, regex rules, and unsupported quick filters run as a per-element scan. A display name can identify different parameters even within one category or class. Scope queries to reduce the scan, or use an explicit parameter identity when appropriate. Numeric rule values are interpreted in the document's display units for that parameter unless 'unit' is given.";
 
         public object ParametersSchema => new
         {
@@ -73,11 +81,17 @@ namespace RevitBridge.Tools
                 type_id = new { type = "integer", description = "Only instances of this element type id (see get_element_types)." },
                 in_active_view = new { type = "boolean", description = "Only elements visible in the active view. Default false." },
                 count_only = new { type = "boolean", description = "Return only total_count, no element rows. Default false." },
+                parameter_names = new
+                {
+                    type = "array", maxItems = 20, items = new { type = "string" },
+                    description = "Optional parameter projections for each returned element: display names, BuiltInParameter names or guid:<GUID>. Every matching parameter is reported, including missing/ambiguous matches. Numeric values use internal units with separate display values. Ignored by count_only.",
+                },
+                include_type_parameters = new { type = "boolean", description = "Also project requested parameters from each element's type. Default false." },
                 fields = new
                 {
                     type = "array",
                     items = new { type = "string", @enum = new[] { "id", "name", "category", "typeName", "levelId" } },
-                    description = "Identity fields per row; default all five. id is always included. Parameter values live in get_element_details.",
+                    description = "Identity fields per row; default all five. id is always included. Use parameter_names for optional values alongside these fields.",
                 },
                 offset = new { type = "integer", description = "Pagination offset. Default 0." },
                 limit = new { type = "integer", description = "Max rows to return (1-1000). Default 200." },
@@ -89,7 +103,7 @@ namespace RevitBridge.Tools
         public IReadOnlyList<string>? PromptGuidelines => new[]
         {
             "Use get_elements to list or count elements of any category or class (walls, doors, rooms, sheets, views, ...); use the returned ids with the other Revit tools.",
-            "get_elements returns identity fields only; read parameter values with get_element_details.",
+            "get_elements can project up to 20 parameter_names per row; use get_element_details for full element inspection.",
         };
 
         public object? Execute(JsonElement args, ToolContext context)
@@ -104,6 +118,9 @@ namespace RevitBridge.Tools
             int offset = Math.Max(0, JsonArgs.GetInt(args, "offset", 0));
             int limit = Math.Clamp(JsonArgs.GetInt(args, "limit", DefaultLimit), 1, MaxLimit);
             var fields = ResolveFields(args);
+            var parameterNames = JsonArgs.GetStringArray(args, "parameter_names");
+            if (parameterNames?.Count > 20) throw new ArgumentException("parameter_names allows at most 20 parameter identities.");
+            bool includeTypeParameters = JsonArgs.GetBool(args, "include_type_parameters", false);
 
             ElementId? categoryId = string.IsNullOrWhiteSpace(categoryInput) ? null : CategoryResolver.Resolve(doc, categoryInput);
             Type? elementClass = string.IsNullOrWhiteSpace(classInput) ? null : ElementClassResolver.Resolve(classInput);
@@ -136,7 +153,7 @@ namespace RevitBridge.Tools
                 return collector;
             }
 
-            var (quickFilter, postPredicate, filterWarnings) = BuildParameterFilter(doc, args, CreateBaseCollector);
+            var (quickFilter, postPredicate, filterWarnings, stickyWarnings) = BuildParameterFilter(doc, args, CreateBaseCollector);
 
             FilteredElementCollector CreateCollector()
             {
@@ -149,7 +166,7 @@ namespace RevitBridge.Tools
             if (countOnly && postPredicate is null)
             {
                 int quickCount = CreateCollector().GetElementCount();
-                return CountResult(scope, quickCount, quickCount > 0 ? Array.Empty<string>() : filterWarnings);
+                return CountResult(scope, quickCount, quickCount > 0 ? stickyWarnings : filterWarnings);
             }
 
             var rows = countOnly ? null : new List<Dictionary<string, object?>>(Math.Min(limit, 256));
@@ -159,15 +176,21 @@ namespace RevitBridge.Tools
                 if (postPredicate != null && !postPredicate(element))
                     continue;
                 if (rows != null && total >= offset && rows.Count < limit)
-                    rows.Add(ElementIdentity.Build(doc, element, fields));
+                {
+                    var row = ElementIdentity.Build(doc, element, fields);
+                    if (parameterNames is { Count: > 0 })
+                        row["parameters"] = GetElementDetails.ProjectParameters(doc, element, parameterNames, includeTypeParameters);
+                    rows.Add(row);
+                }
                 total++;
             }
 
-            // A found match proves the query worked: the not-found-on-probes warning is
+            // A found match proves most rules worked: a not-found-on-probes warning is
             // load-bearing only next to a zero, where it distinguishes 'unknown parameter
-            // name' from 'no matching elements'. Beside real matches it is just noise.
+            // name' from 'no matching elements'. is_empty warnings stay, because a missing
+            // parameter can itself produce the matches (inv:missing-not-silent).
             if (total > 0)
-                filterWarnings = Array.Empty<string>();
+                filterWarnings = stickyWarnings;
 
             if (rows is null)
                 return CountResult(scope, total, filterWarnings);
@@ -272,17 +295,18 @@ namespace RevitBridge.Tools
             public required RuleOp Op { get; init; }
             public JsonElement Value { get; init; }
             public string? Unit { get; init; }
+            public required ParameterReference Reference { get; init; }
             public BuiltInParameter? BuiltIn { get; init; }
             public Guid? SharedGuid { get; init; }
             public Regex? CompiledRegex { get; init; }
             public FilterRule? QuickRule { get; set; }
         }
 
-        private static (ElementFilter? Quick, Func<Element, bool>? Post, IReadOnlyList<string> Warnings) BuildParameterFilter(
+        private static (ElementFilter? Quick, Func<Element, bool>? Post, IReadOnlyList<string> Warnings, IReadOnlyList<string> StickyWarnings) BuildParameterFilter(
             Document doc, JsonElement args, Func<FilteredElementCollector> createBaseCollector)
         {
             if (args.ValueKind != JsonValueKind.Object || !args.TryGetProperty("filter", out var filterElement) || filterElement.ValueKind != JsonValueKind.Object)
-                return (null, null, Array.Empty<string>());
+                return (null, null, Array.Empty<string>(), Array.Empty<string>());
 
             bool matchAny = string.Equals(JsonArgs.GetString(filterElement, "match"), "any", StringComparison.OrdinalIgnoreCase);
             if (!filterElement.TryGetProperty("rules", out var rulesElement) || rulesElement.ValueKind != JsonValueKind.Array)
@@ -290,7 +314,7 @@ namespace RevitBridge.Tools
 
             var rules = rulesElement.EnumerateArray().Select(ParseRule).ToList();
             if (rules.Count == 0)
-                return (null, null, Array.Empty<string>());
+                return (null, null, Array.Empty<string>(), Array.Empty<string>());
 
             // Probe a few in-scope elements for missing-name diagnostics and to find
             // storage/spec exemplars for explicit parameter identities. A sample must
@@ -311,13 +335,25 @@ namespace RevitBridge.Tools
             // A warning (not an error: the parameter may exist past the probe window,
             // and is_empty legitimately matches missing parameters) makes the zero honest.
             var warnings = new List<string>();
+            var stickyWarnings = new List<string>();
             if (probes.Count > 0)
             {
                 foreach (var rule in rules)
                 {
                     if (rule.BuiltIn != null || rule.SharedGuid != null)
                         continue;
-                    if (probes.All(probe => FindParameter(probe, rule) is null))
+                    if (probes.All(probe => FindParameter(probe, rule) is null) && rule.Op == RuleOp.IsEmpty)
+                    {
+                        // inv:missing-not-silent: is_empty matches elements that lack the parameter,
+                        // so a misspelled or localized name matches the whole scope. Keep this warning.
+                        string sticky = $"Filter parameter '{rule.ParamInput}' was not found on any of the {probes.Count} probed element(s) in scope. "
+                            + "is_empty also matches elements that do not have the parameter at all, so these results may be elements without it "
+                            + "rather than elements with an empty value. Check the name, or use the language-independent BuiltInParameter name or guid:<GUID> "
+                            + "(get_element_details reports builtInParameter per parameter).";
+                        warnings.Add(sticky);
+                        stickyWarnings.Add(sticky);
+                    }
+                    else if (probes.All(probe => FindParameter(probe, rule) is null))
                         warnings.Add(
                             $"Filter parameter '{rule.ParamInput}' was not found on any of the {probes.Count} probed element(s) in scope, "
                             + "so a 0-match result may mean 'unknown parameter name', not 'no matching elements'. Display names are "
@@ -349,10 +385,10 @@ namespace RevitBridge.Tools
                 // OR with any post-scan rule means everything must be post-scanned: a
                 // collector-level OR filter would wrongly exclude post-rule-only matches.
                 if (postRules.Count > 0)
-                    return (null, element => rules.Any(rule => EvaluatePost(doc, element, rule)), warnings);
+                    return (null, element => rules.Any(rule => EvaluatePost(doc, element, rule)), warnings, stickyWarnings);
 
                 var filters = quickRules.Select(rule => (ElementFilter)new ElementParameterFilter(rule.QuickRule!)).ToList();
-                return (filters.Count == 1 ? filters[0] : new LogicalOrFilter(filters), null, warnings);
+                return (filters.Count == 1 ? filters[0] : new LogicalOrFilter(filters), null, warnings, stickyWarnings);
             }
 
             ElementFilter? quick = quickRules.Count > 0
@@ -361,7 +397,7 @@ namespace RevitBridge.Tools
             Func<Element, bool>? post = postRules.Count > 0
                 ? element => postRules.All(rule => EvaluatePost(doc, element, rule))
                 : null;
-            return (quick, post, warnings);
+            return (quick, post, warnings, stickyWarnings);
         }
 
         private static Rule ParseRule(JsonElement element)
@@ -393,26 +429,7 @@ namespace RevitBridge.Tools
             if (!hasValue && op is not (RuleOp.IsEmpty or RuleOp.IsNotEmpty))
                 throw new ArgumentException($"Filter rule on '{param}' with op {opText} needs a value.");
 
-            BuiltInParameter? builtIn = null;
-            Guid? sharedGuid = null;
-            if (param.StartsWith("guid:", StringComparison.OrdinalIgnoreCase))
-            {
-                sharedGuid = Guid.TryParse(param["guid:".Length..], out var guid)
-                    ? guid
-                    : throw new ArgumentException($"Invalid shared parameter guid: {param}");
-            }
-            else
-            {
-                string enumName = param.StartsWith("BuiltInParameter.", StringComparison.OrdinalIgnoreCase)
-                    ? param["BuiltInParameter.".Length..]
-                    : param;
-                // BuiltInParameter names are SHOUTY_SNAKE_CASE; require an underscore or
-                // all-caps so plain display names like "Comments" never collide.
-                bool looksLikeEnumName = enumName.Length > 0 && char.IsLetter(enumName[0]) && !enumName.Contains(' ')
-                    && (enumName.Contains('_') || enumName.All(c => !char.IsLetter(c) || char.IsUpper(c)));
-                if (looksLikeEnumName && Enum.TryParse<BuiltInParameter>(enumName, true, out var parsed) && parsed != BuiltInParameter.INVALID)
-                    builtIn = parsed;
-            }
+            var reference = ParameterReference.Parse(param);
 
             Regex? regex = null;
             if (op == RuleOp.Regex)
@@ -434,29 +451,15 @@ namespace RevitBridge.Tools
                 Op = op,
                 Value = hasValue ? value : default,
                 Unit = JsonArgs.GetString(element, "unit"),
-                BuiltIn = builtIn,
-                SharedGuid = sharedGuid,
+                Reference = reference,
+                BuiltIn = reference.BuiltIn,
+                SharedGuid = reference.SharedGuid,
                 CompiledRegex = regex,
             };
         }
 
-        private static Parameter? FindParameter(Element element, Rule rule)
-        {
-            if (rule.BuiltIn is { } builtIn)
-                return element.get_Parameter(builtIn);
-            if (rule.SharedGuid is { } guid)
-                return element.get_Parameter(guid);
-
-            var direct = element.LookupParameter(rule.ParamInput);
-            if (direct != null)
-                return direct;
-            foreach (Parameter parameter in element.Parameters)
-            {
-                if (string.Equals(parameter.Definition?.Name, rule.ParamInput, StringComparison.OrdinalIgnoreCase))
-                    return parameter;
-            }
-            return null;
-        }
+        /// <summary>Shared resolution policy: missing is null; an ambiguous display name throws with candidates.</summary>
+        private static Parameter? FindParameter(Element element, Rule rule) => ParameterResolver.FindSingle(element, rule.Reference);
 
         /// <summary>Builds a collector-level FilterRule, or null when the op/storage pair must post-scan.</summary>
         private static FilterRule? TryBuildQuickRule(Document doc, Rule rule, Parameter exemplar)