pi-revit 0.3.1 → 0.5.0

package/src/Revit/Tools/ModelEditInputs.cs

@@ -0,0 +1,49 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal static class ModelEditInputs
+{
+    public static object IdsSchema => new { type = "array", minItems = 1, maxItems = 200, uniqueItems = true, items = new { type = "integer", minimum = 1 } };
+    public static object PreviewSchema => new { type = "boolean", description = "Commit-validate then roll back all model edits. Default false." };
+    public static object LengthUnitSchema => new { type = "string", @enum = new[] { "millimeters", "centimeters", "meters", "feet", "inches" } };
+    public static object VectorSchema(string description) => new { type = "array", minItems = 3, maxItems = 3, items = new { type = "number" }, description };
+    public static List<ElementId> Ids(JsonElement args)
+    {
+        var ids = JsonArgs.GetLongArray(args, "element_ids");
+        if (ids.Count is < 1 or > 200 || ids.Any(id => id <= 0) || ids.Distinct().Count() != ids.Count)
+            throw new ArgumentException("element_ids must contain 1–200 distinct positive IDs.");
+        return ids.Select(id => new ElementId(id)).ToList();
+    }
+    public static double LengthScale(JsonElement args) => JsonArgs.GetString(args, "unit") switch
+    {
+        "millimeters" => 1 / 304.8, "centimeters" => 1 / 30.48, "meters" => 1 / 0.3048,
+        "feet" => 1, "inches" => 1 / 12.0,
+        _ => throw new ArgumentException("unit must be millimeters, centimeters, meters, feet or inches."),
+    };
+    public static double Number(JsonElement args, string name)
+    {
+        if (!args.TryGetProperty(name, out var value) || value.ValueKind != JsonValueKind.Number || !value.TryGetDouble(out double number) || !double.IsFinite(number))
+            throw new ArgumentException($"{name} must be a finite number.");
+        return number;
+    }
+    public static XYZ Vector(JsonElement args, string name)
+    {
+        if (!args.TryGetProperty(name, out var values) || values.ValueKind != JsonValueKind.Array || values.GetArrayLength() != 3)
+            throw new ArgumentException($"{name} must contain exactly three finite numbers.");
+        var numbers = values.EnumerateArray().Select(v => v.ValueKind == JsonValueKind.Number && v.TryGetDouble(out double n) && double.IsFinite(n) ? n : throw new ArgumentException($"{name} must contain finite numbers.")).ToArray();
+        return new XYZ(numbers[0], numbers[1], numbers[2]);
+    }
+    public static object Snapshot(Element element)
+    {
+        static double[] Point(XYZ p) => new[] { p.X, p.Y, p.Z };
+        object? location = element.Location switch
+        {
+            LocationPoint p => new { kind = "point", point = Point(p.Point) },
+            LocationCurve c when c.Curve.IsBound => new { kind = "curve_endpoints", start = Point(c.Curve.GetEndPoint(0)), end = Point(c.Curve.GetEndPoint(1)) } as object,
+            _ => null,
+        };
+        return new { id = element.Id.Value, unique_id = element.UniqueId, name = element.Name, type_id = element.GetTypeId().Value, location };
+    }
+}

package/src/Revit/Tools/OpenView.cs

@@ -13,9 +13,17 @@ namespace RevitBridge.Tools
     internal sealed class OpenView : ITool
     {
         public string Name => "open_view";
+        public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+        public IReadOnlyList<string> Keywords => new[] { "open", "show", "activate", "switch view", "go to sheet", "display" };
+        public IReadOnlyList<ToolLimit> Limits => new[]
+        {
+            new ToolLimit("Creating views", "tool", "manage_views"),
+        };
+        public string? Verification => "none";
         public string Label => "Open View";
         public string Description => "Activate a view or sheet in the Revit UI, like double-clicking it in the Project Browser. Identify the target by view_id (an id from get_elements category Views/Sheets or from view/sheet creation) or by name (exact view name, sheet number like 'A-101', or sheet number - name; case-insensitive). Activation is queued and completes the instant this call returns control to Revit — a capture_view immediately after may still show the previous active view. View templates and internal views cannot be opened.";
         public bool Write => false;
+        public IReadOnlyList<string> Effects => new[] { "ui" };
 
         public object ParametersSchema => new
         {

package/src/Revit/Tools/ParameterResolver.cs

@@ -0,0 +1,94 @@
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools
+{
+    /// <summary>
+    /// A caller's parameter reference: <c>guid:&lt;GUID&gt;</c> for a shared parameter, a
+    /// BuiltInParameter name (SHOUTY_SNAKE_CASE or <c>BuiltInParameter.NAME</c>), or a
+    /// localized display name. One parsing rule for every tool.
+    /// </summary>
+    internal readonly record struct ParameterReference(string Input, BuiltInParameter? BuiltIn, Guid? SharedGuid)
+    {
+        public bool IsDisplayName => BuiltIn is null && SharedGuid is null;
+
+        public static ParameterReference Parse(string input)
+        {
+            string text = input.Trim();
+            if (text.StartsWith("guid:", StringComparison.OrdinalIgnoreCase))
+                return Guid.TryParse(text["guid:".Length..], out var guid)
+                    ? new ParameterReference(text, null, guid)
+                    : throw new ArgumentException($"Invalid shared parameter guid: {text}");
+            string enumName = text.StartsWith("BuiltInParameter.", StringComparison.OrdinalIgnoreCase)
+                ? text["BuiltInParameter.".Length..]
+                : text;
+            // 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)
+                return new ParameterReference(text, parsed, null);
+            return new ParameterReference(text, null, null);
+        }
+    }
+
+    /// <summary>
+    /// The single parameter-resolution policy for every tool (inv:parameter-ambiguity).
+    /// Exact identities resolve to at most one parameter. A display name returns every
+    /// parameter with that name (exact case first, then case-insensitive), because Revit
+    /// elements can carry several same-named parameters and <c>LookupParameter</c> would
+    /// silently return an arbitrary one. Writes and filters use <see cref="FindSingle"/>,
+    /// which rejects ambiguity with the candidates' exact identities; projections use
+    /// <see cref="FindAll"/> and report ambiguity. Missing (null) is distinct from empty.
+    /// </summary>
+    internal static class ParameterResolver
+    {
+        public static IReadOnlyList<Parameter> FindAll(Element element, ParameterReference reference)
+        {
+            if (reference.BuiltIn is { } builtIn)
+                return One(element.get_Parameter(builtIn));
+            if (reference.SharedGuid is { } guid)
+                return One(element.get_Parameter(guid));
+            // GetParameters is Revit's native exact-name lookup returning every match.
+            var exact = element.GetParameters(reference.Input);
+            if (exact.Count > 0)
+                return Distinct(exact);
+            var folded = new List<Parameter>();
+            foreach (Parameter parameter in element.Parameters)
+                if (string.Equals(parameter.Definition?.Name, reference.Input, StringComparison.OrdinalIgnoreCase))
+                    folded.Add(parameter);
+            return Distinct(folded);
+        }
+
+        /// <summary>The one matching parameter, null when missing; throws when ambiguous.</summary>
+        public static Parameter? FindSingle(Element element, ParameterReference reference)
+        {
+            var matches = FindAll(element, reference);
+            return matches.Count switch
+            {
+                0 => null,
+                1 => matches[0],
+                _ => throw new ArgumentException(AmbiguityMessage(element, reference, matches)),
+            };
+        }
+
+        public static string AmbiguityMessage(Element element, ParameterReference reference, IReadOnlyList<Parameter> matches)
+            => $"Parameter '{reference.Input}' is ambiguous on element {element.Id.Value}: {matches.Count} parameters share that display name "
+               + $"({string.Join("; ", matches.Select(Identity))}). Nothing was chosen. Use one of these exact identities instead.";
+
+        /// <summary>The language-independent identity a caller can pass back.</summary>
+        public static string Identity(Parameter parameter)
+        {
+            if (parameter.IsShared)
+                return $"guid:{parameter.GUID}";
+            if (parameter.Definition is InternalDefinition definition && definition.BuiltInParameter != BuiltInParameter.INVALID)
+                return definition.BuiltInParameter.ToString();
+            return $"'{parameter.Definition?.Name}' (parameter id {parameter.Id.Value}, no language-independent identity)";
+        }
+
+        private static IReadOnlyList<Parameter> One(Parameter? parameter)
+            => parameter is null ? Array.Empty<Parameter>() : new[] { parameter };
+
+        private static IReadOnlyList<Parameter> Distinct(IEnumerable<Parameter> parameters)
+            => parameters.GroupBy(parameter => parameter.Id.Value).Select(group => group.First()).ToList();
+    }
+}

package/src/Revit/Tools/QuerySpatialElements.cs

@@ -0,0 +1,70 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class QuerySpatialElements : ITool
+{
+    public string Name => "query_spatial_elements";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.ProjectOnly;
+    public IReadOnlyList<string> Keywords => new[] { "inside", "within", "contained", "intersect", "bounding box", "spatial", "near", "clash candidates", "overlap" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("Solid-intersection clash detection", "api", "ElementIntersectsElementFilter; ElementIntersectsSolidFilter"),
+        new ToolLimit("Elements inside linked models", "tool", "get_linked_elements with host_bounds"),
+    };
+    public string Label => "Query Spatial Elements";
+    public string Tier => "advanced";
+    public string Description => "Find host elements whose model axis-aligned bounding boxes intersect or lie inside an explicit region. Coordinates use document internal axes and the required length unit. query uses get_elements filters, covering the whole scope (maximum 10,000 candidates). Includes touching boundaries; elements without bounds are counted separately. Bounds may include nonphysical geometry, so these are approximate candidates, not solid intersections or clashes. Linked contents are not traversed. Results are ordered by element ID with paging.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            query = ElementQueryScope.Schema(),
+            min = ModelEditInputs.VectorSchema("Region minimum in document internal axes, in unit."),
+            max = ModelEditInputs.VectorSchema("Region maximum in document internal axes, in unit."),
+            unit = ModelEditInputs.LengthUnitSchema,
+            relation = new { type = "string", @enum = new[] { "intersects", "inside" } },
+            offset = new { type = "integer", minimum = 0 }, limit = new { type = "integer", minimum = 1, maximum = 200 },
+        }, required = new[] { "min", "max", "unit" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        double scale = ModelEditInputs.LengthScale(args);
+        var region = new SpatialBounds(ModelEditInputs.Vector(args, "min").Multiply(scale), ModelEditInputs.Vector(args, "max").Multiply(scale));
+        if (region.Min.X > region.Max.X || region.Min.Y > region.Max.Y || region.Min.Z > region.Max.Z)
+            throw new ArgumentException("Each min coordinate must be less than or equal to max.");
+        string relation = JsonArgs.GetString(args, "relation") ?? "intersects";
+        if (relation is not ("intersects" or "inside")) throw new ArgumentException("relation must be intersects or inside.");
+        var query = ElementQueryScope.Parse(args);
+        JsonElement RunQuery() => JsonSerializer.SerializeToElement(((ToolOutput)new GetElements().Execute(JsonSerializer.SerializeToElement(query), context)!).Payload);
+        query["count_only"] = true;
+        var counted = RunQuery();
+        int count = counted.GetProperty("total_count").GetInt32();
+        if (count > 10000) throw new ArgumentException($"Query has {count} candidates; narrow query to at most 10,000.");
+        object? warnings = counted.TryGetProperty("warnings", out var warning) ? warning.Clone() : null;
+        query["count_only"] = false; query["limit"] = 1000;
+        var matches = new List<(Element Element, SpatialBounds Bounds)>();
+        int withoutBounds = 0;
+        for (int start = 0; start < count; start += 1000)
+        {
+            query["offset"] = start;
+            foreach (var row in RunQuery().GetProperty("elements").EnumerateArray())
+            {
+                var element = doc.GetElement(new ElementId(row.GetProperty("id").GetInt64()));
+                var bounds = SpatialBounds.Of(element);
+                if (bounds == null) { withoutBounds++; continue; }
+                if (relation == "inside" ? region.Contains(bounds) : region.Intersects(bounds)) matches.Add((element, bounds));
+            }
+        }
+        int offset = Math.Max(0, JsonArgs.GetInt(args, "offset", 0)), limit = Math.Clamp(JsonArgs.GetInt(args, "limit", 100), 1, 200);
+        var elements = matches.OrderBy(x => x.Element.Id.Value).Skip(offset).Take(limit).Select(x => new
+        {
+            id = x.Element.Id.Value, unique_id = x.Element.UniqueId, name = x.Element.Name, category = x.Element.Category?.Name, bounds = x.Bounds.Describe(scale),
+        }).ToArray();
+        return new { method = "axis_aligned_bounding_boxes", approximate = true, coordinate_system = "document_internal", unit = JsonArgs.GetString(args, "unit"),
+            relation, region = region.Describe(scale), candidate_count = count, without_bounds_count = withoutBounds, warnings,
+            total_count = matches.Count, offset, returned_count = elements.Length, next_offset = offset + elements.Length < matches.Count ? (int?)(offset + elements.Length) : null, elements };
+    }
+}

package/src/Revit/Tools/SearchApiDocs.cs

@@ -33,8 +33,15 @@ namespace RevitBridge.Tools
         private const int MaxExceptionsPerMember = 8;
 
         public string Name => "search_api_docs";
+        public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+        public IReadOnlyList<string> Keywords => new[] { "api", "revit api", "method", "class", "signature", "enum", "developer documentation" };
+        public IReadOnlyList<ToolLimit> Limits => new[]
+        {
+            new ToolLimit("Autodesk product Help or modeling guidance", "user", "Autodesk Revit Help or project standards"),
+            new ToolLimit("Proof that code compiles or works", "tool", "execute_csharp"),
+        };
         public string Label => "Search API Docs";
-        public string Description => "Search the offline Revit API documentation (the RevitAPI.xml and RevitAPIUI.xml files shipped with Revit) for types, methods, constructors, properties, fields, and events; every public API enum is fully searchable by value name (values the XML leaves undocumented are synthesized from the API assemblies). query is a single name or substring — e.g. 'FilteredElementCollector', 'Wall.Create', 'WALL_BASE_OFFSET' — ranked: exact name first, then prefix, then substring; dotted Type.Member queries match composites, and same-named overloads rank simplest-first. To target one overload, continue the query past a parenthesis with parameter types, e.g. 'Wall.Create(Document, Curve'. Returns signatures with summary, remarks, parameter docs, return docs, exception docs, and the Revit version a member was introduced in ('since'); the top match shows its full docs inline. Works with no document open. Use it to verify exact classes, members, and signatures before writing execute_csharp code. The first query builds the index (a few seconds); later queries are instant.";
+        public string Description => "Search the offline Revit API documentation (the RevitAPI.xml and RevitAPIUI.xml files shipped with Revit) for types, methods, constructors, properties, fields, and events; every public API enum is fully searchable by value name (values the XML leaves undocumented are synthesized from the API assemblies). query is a name or substring — e.g. 'FilteredElementCollector', 'Wall.Create', 'WALL_BASE_OFFSET' — ranked: exact name first, then prefix, then substring; dotted Type.Member queries match composites, and same-named overloads rank simplest-first. To target one overload, continue the query past a parenthesis with parameter types, e.g. 'Wall.Create(Document, Curve'. Returns signatures with summary, remarks, parameter docs, return docs, exception docs, and the Revit version a member was introduced in ('since'); the top match shows its full docs inline. To verify several members at once, separate them with ';' (up to 10, e.g. 'View3D.CreatePerspective; ViewOrientation3D', the form declared API limits use): each gets its best match with compact docs. Works with no document open. Use it to verify exact classes, members, and signatures before writing execute_csharp code. The first query builds the index (a few seconds); later queries are instant.";
 
         public bool RequiresDocument => false;
 
@@ -46,7 +53,7 @@ namespace RevitBridge.Tools
                 query = new
                 {
                     type = "string",
-                    description = "Type or member name to look up, e.g. FilteredElementCollector, Wall.Create, WALL_BASE_OFFSET. Substring and multi-word matches are ranked; Type.Member composites rank highest on exact match.",
+                    description = "Type or member name to look up, e.g. FilteredElementCollector, Wall.Create, WALL_BASE_OFFSET; or up to 10 names separated by ';' to verify them in one call. Substring and multi-word matches are ranked; Type.Member composites rank highest on exact match.",
                 },
                 kind = new
                 {
@@ -57,7 +64,7 @@ namespace RevitBridge.Tools
                 max_results = new
                 {
                     type = "integer",
-                    description = $"Maximum matches to return (1-{MaxResultsCap}, default {DefaultMaxResults}).",
+                    description = $"Maximum matches to return (1-{MaxResultsCap}, default {DefaultMaxResults}; per member when several are named, default {DefaultResultsPerMember}).",
                 },
             },
             required = new[] { "query" },
@@ -66,7 +73,7 @@ namespace RevitBridge.Tools
         public string? PromptSnippet => "Search the offline Revit API documentation for types, members, and signatures.";
         public IReadOnlyList<string>? PromptGuidelines => new[]
         {
-            "Before writing execute_csharp code, verify exact classes and member signatures with search_api_docs (e.g. query 'Wall.Create' or 'FilteredElementCollector').",
+            "Before writing execute_csharp code, verify exact classes and member signatures with search_api_docs; name all members you need in one query separated by ';' (e.g. 'View3D.CreatePerspective; ViewOrientation3D; View.CropBox').",
         };
 
         public object? Execute(JsonElement args, ToolContext context)
@@ -81,6 +88,12 @@ namespace RevitBridge.Tools
             if (index.Members.Count == 0)
                 throw new InvalidOperationException("The Revit API documentation index is empty. " + string.Join(" ", index.Warnings));
 
+            var parts = SplitQueries(query);
+            if (parts.Count > MaxQueriesPerCall)
+                throw new ArgumentException($"query names {parts.Count} members; look up at most {MaxQueriesPerCall} per call.");
+            if (parts.Count > 1)
+                return ExecuteMany(index, parts, kindFilter, args.TryGetProperty("max_results", out _) ? maxResults : DefaultResultsPerMember);
+
             var (top, total, rewriteNote) = Search(index, query, kindFilter, maxResults);
 
             var matches = new List<Dictionary<string, object?>>(top.Count);
@@ -119,10 +132,65 @@ namespace RevitBridge.Tools
             }, BuildMarkdown(query, top, total, index) + (rewriteNote is null ? string.Empty : $"\nNote: {rewriteNote}"));
         }
 
+        private const int DefaultResultsPerMember = 3;
+        private const int ManyRemarksChars = 300;
+        private const int ManyParamDocChars = 160;
+
+        /// <summary>Several members in one call: the best match of each with compact docs, plus
+        /// the next candidates by signature only, so a script's members are verified together.</summary>
+        private static ToolOutput ExecuteMany(DocIndex index, IReadOnlyList<string> parts, char? kindFilter, int perQuery)
+        {
+            var lookups = LookUpMany(index, parts, kindFilter, perQuery);
+            var results = lookups.Select(lookup => new Dictionary<string, object?>
+            {
+                ["query"] = lookup.Query,
+                ["totalMatches"] = lookup.Total,
+                ["best"] = lookup.Top.Count == 0 ? null : new Dictionary<string, object?>
+                {
+                    ["kind"] = KindLabel(lookup.Top[0]), ["name"] = lookup.Top[0].FullName, ["signature"] = lookup.Top[0].Signature, ["since"] = lookup.Top[0].Since,
+                    ["summary"] = lookup.Top[0].Summary, ["remarks"] = Cap(lookup.Top[0].Remarks, ManyRemarksChars),
+                    ["parameters"] = lookup.Top[0].Parameters?.Select(pair => new Dictionary<string, object?> { ["name"] = pair.Key, ["description"] = Cap(pair.Value, ManyParamDocChars) }).ToList(),
+                    ["returns"] = Cap(lookup.Top[0].Returns, ManyParamDocChars),
+                    // Exceptions state when a member refuses (for example "not a project document").
+                    ["exceptions"] = lookup.Top[0].Exceptions?.Take(3).Select(pair => $"{pair.Key}: {Cap(FirstSentence(pair.Value), 140)}").ToList(),
+                },
+                ["alternatives"] = lookup.Top.Skip(1).Select(member => new Dictionary<string, object?> { ["kind"] = KindLabel(member), ["signature"] = member.Signature }).ToList(),
+                ["note"] = lookup.Total == 0 ? "No match. Try a shorter name or the type alone." : lookup.Note,
+            }).ToList();
+            var markdown = new StringBuilder($"Revit API docs for {parts.Count} members:");
+            foreach (var lookup in lookups)
+                markdown.Append(lookup.Top.Count == 0 ? $"\n- '{lookup.Query}': no match" : $"\n- '{lookup.Query}': **{lookup.Top[0].Signature}** — {FirstSentence(lookup.Top[0].Summary) ?? "(no summary)"}");
+            return new ToolOutput(new
+            {
+                query = string.Join("; ", parts),
+                lookups = parts.Count,
+                results,
+                indexedMembers = index.Members.Count,
+                sources = index.SourceFiles,
+                warnings = index.Warnings.Count > 0 ? index.Warnings : null,
+            }, markdown.ToString());
+        }
+
         // ----------------------------------------------------------------- search
 
         private static readonly char[] WordSeparators = { '.', ' ', '_', '(', ')', ',', ':', '-', '/' };
 
+        /// <summary>Most members one multi-member lookup ("A; B; C") may name.</summary>
+        private const int MaxQueriesPerCall = 10;
+
+        /// <summary>A query naming several members separated by ';' (the form declared API
+        /// limits use) is looked up member by member in one call; duplicates are dropped.</summary>
+        private static List<string> SplitQueries(string query) => query
+            .Split(';', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)
+            .Distinct(StringComparer.OrdinalIgnoreCase).ToList();
+
+        private static List<(string Query, List<ApiMember> Top, int Total, string? Note)> LookUpMany(DocIndex index, IReadOnlyList<string> queries, char? kindFilter, int perQuery)
+            => queries.Select(part =>
+            {
+                var (top, total, note) = Search(index, part, kindFilter, perQuery);
+                return (part, top, total, note);
+            }).ToList();
+
         private static (List<ApiMember> Top, int Total, string? RewriteNote) Search(DocIndex index, string query, char? kindFilter, int maxResults)
         {
             // Signatures are rendered exactly one way ("Name(Type, Type)"): normalize the

package/src/Revit/Tools/SetParameters.cs

@@ -18,8 +18,18 @@ namespace RevitBridge.Tools
         private const int MaxUpdates = 200;
 
         public string Name => "set_parameters";
+        public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+        public IReadOnlyList<string> Keywords => new[] { "parameter", "set value", "edit", "change value", "rename", "mark", "comments", "bulk edit", "update" };
+        public IReadOnlyList<ToolLimit> Limits => new[]
+        {
+            new ToolLimit("Changing an element's type", "tool", "change_element_types"),
+            new ToolLimit("Element properties that are not parameters, such as pinned state", "api", "Element.Pinned"),
+            new ToolLimit("Moving or rotating elements", "tool", "transform_elements"),
+            new ToolLimit("Family parameters, family types and formulas in a family document", "api", DocumentKind.FamilyApi),
+        };
+        public string? Verification => "reread";
         public string Label => "Set Parameters";
-        public string Description => "Write parameter values on elements — also the home for rename: parameter 'Name' covers levels, views, sheets, types, etc. (falls back to the element's Name property when the Name parameter is read-only). updates apply in ONE transaction: partial success commits and lists the failures; if every update fails the transaction is rolled back and nothing changes. parameter accepts a display name (Comments, Mark, Name), a BuiltInParameter enum name (e.g. ALL_MODEL_MARK), or guid:<GUID> for a shared parameter; type parameters live on the element type, so pass the type's id. Values are validated against the parameter's storage type; numeric values are interpreted in the document's display units for that parameter unless 'unit' (e.g. millimeters, feet, squareMeters) is given. Revit warnings raised at commit (e.g. duplicate Mark values) are auto-dismissed and listed in commitWarnings — mention them to the user; error-severity failures roll the whole transaction back.";
+        public string Description => "Write parameter values on elements — also the home for rename: parameter 'Name' covers levels, views, sheets, types, etc. (falls back to the element's Name property when the Name parameter is read-only). Each update has its own subtransaction inside one model transaction. Default partial success commits valid updates; atomic=true rolls everything back if any update fails. preview=true validates commit inside a transaction group, then rolls the group back. Results include observed per-step before/after values and distinguish succeeded from proposed updates. parameter accepts a display name (Comments, Mark, Name), a BuiltInParameter enum name (e.g. ALL_MODEL_MARK), or guid:<GUID> for a shared parameter; type parameters live on the element type, so pass the type's id. Values are validated against the parameter's storage type; numeric values are interpreted in the document's display units for that parameter unless 'unit' (e.g. millimeters, feet, squareMeters) is given. Revit warnings raised at commit (e.g. duplicate Mark values) are auto-dismissed and listed in commitWarnings — mention them to the user; error-severity failures roll the whole transaction back.";
         public bool Write => true;
 
         public object ParametersSchema => new
@@ -27,6 +37,8 @@ namespace RevitBridge.Tools
             type = "object",
             properties = new
             {
+                preview = new { type = "boolean", description = "Validate edits through Revit commit, then roll back the enclosing transaction group. Returns proposed before/after values; no model changes remain. Default false." },
+                atomic = new { type = "boolean", description = "Roll back all updates if any fails. Default false preserves successful updates. Each update is isolated in a subtransaction." },
                 updates = new
                 {
                     type = "array",
@@ -57,7 +69,7 @@ namespace RevitBridge.Tools
         public IReadOnlyList<string>? PromptGuidelines => new[]
         {
             "Use set_parameters for parameter writes and renames (parameter 'Name'); pass 'unit' with numeric values unless the document's display units are intended.",
-            "set_parameters commits partial successes — always check the failed list in its result instead of assuming every update applied.",
+            "set_parameters defaults to partial success; use atomic=true for all-or-nothing batches and preview=true for commit-validated model rollback. Always inspect committed, proposed and failed.",
         };
 
         public object? Execute(JsonElement args, ToolContext context)
@@ -65,87 +77,32 @@ namespace RevitBridge.Tools
             var doc = context.Document ?? throw new NoActiveDocumentException();
             DocumentGuard.CheckExpectedDocument(args, doc);
             var updates = ParseUpdates(args);
-
-            var succeeded = new List<Dictionary<string, object?>>();
-            var failed = new List<Dictionary<string, object?>>();
-
-            using var transaction = new Transaction(doc, "set_parameters");
-            if (transaction.Start() != TransactionStatus.Started)
-                throw new InvalidOperationException("Unable to start the set_parameters transaction.");
-            var failureGuard = FailureGuard.Attach(transaction);
-
-            try
-            {
-                foreach (var update in updates)
+            var steps = updates.Select(update => new ModelEditBatch.Step(
+                new Dictionary<string, object?> { ["id"] = update.ElementId, ["parameter"] = update.ParameterInput },
+                () =>
                 {
-                    try
-                    {
-                        string? newDisplayValue = Apply(doc, update);
-                        succeeded.Add(new Dictionary<string, object?>
-                        {
-                            ["id"] = update.ElementId,
-                            ["parameter"] = update.ParameterInput,
-                            ["newDisplayValue"] = newDisplayValue,
-                        });
-                    }
-                    catch (Exception ex)
+                    var change = Apply(doc, update);
+                    return new Dictionary<string, object?>
                     {
-                        failed.Add(new Dictionary<string, object?>
-                        {
-                            ["id"] = update.ElementId,
-                            ["parameter"] = update.ParameterInput,
-                            ["reason"] = ex.Message,
-                        });
-                    }
-                }
-
-                if (succeeded.Count > 0)
-                {
-                    var status = transaction.Commit();
-                    var finalStatus = transaction.GetStatus();
-                    if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
-                        throw new InvalidOperationException(
-                            $"The set_parameters commit returned {status}; current transaction status is {finalStatus}."
-                            + failureGuard.DescribeErrors());
-                }
-                else
-                {
-                    var status = transaction.RollBack();
-                    if (status != TransactionStatus.RolledBack || transaction.GetStatus() != TransactionStatus.RolledBack)
-                        throw new InvalidOperationException($"The set_parameters rollback returned {status}.");
-                }
-            }
-            catch (Exception ex)
-            {
-                throw new InvalidOperationException($"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}", ex);
-            }
-
-            int elementCount = succeeded.Select(row => row["id"]).Distinct().Count();
-            string failureSample = failed.Count > 0
-                ? $" First failure: element {failed[0]["id"]} '{failed[0]["parameter"]}': {failed[0]["reason"]}"
-                : string.Empty;
-            string compact = failed.Count == 0
-                ? $"Updated {succeeded.Count} parameter value(s) on {elementCount} element(s)."
-                : succeeded.Count == 0
-                    ? $"No updates applied; all {failed.Count} failed — transaction rolled back.{failureSample}"
-                    : $"Updated {succeeded.Count} parameter value(s) on {elementCount} element(s); {failed.Count} failed.{failureSample}";
-            if (failureGuard.Warnings.Count > 0)
-                compact += $" {failureGuard.Warnings.Count} Revit warning(s) auto-dismissed at commit (see commitWarnings), e.g.: {failureGuard.Warnings[0]}";
-
-            return new ToolOutput(new
-            {
-                updated = succeeded.Count,
-                committed = succeeded.Count > 0,
-                succeeded,
-                failed,
-                commitWarnings = failureGuard.Warnings,
-            }, compact);
+                        ["before"] = change.Before, ["after"] = change.After,
+                        ["newDisplayValue"] = change.Display,
+                    };
+                })).ToArray();
+            var result = ModelEditBatch.Run(doc, Name, args, steps);
+            string summary = result.Preview
+                ? $"Preview rolled back: {result.Proposed.Count} proposed update(s), {result.Failed.Count} failure(s)."
+                : result.Committed
+                    ? $"Applied {result.Succeeded.Count} parameter update(s); {result.Failed.Count} failed."
+                    : $"No updates applied; {result.Failed.Count} failed. Batch rolled back.";
+            return new ToolOutput(result.Payload, summary);
         }
 
         // ------------------------------------------------------------- application
 
-        /// <summary>Applies one update; returns the new display value or throws with the per-update reason.</summary>
-        private static string? Apply(Document doc, Update update)
+        private sealed record ValueChange(string? Display, object? Before, object? After);
+
+        /// <summary>Snapshots the concrete parameter or rename target actually written by this step.</summary>
+        private static ValueChange Apply(Document doc, Update update)
         {
             var element = doc.GetElement(new ElementId(update.ElementId))
                 ?? throw new InvalidOperationException($"Element {update.ElementId} not found.");
@@ -168,6 +125,7 @@ namespace RevitBridge.Tools
                 throw new InvalidOperationException($"Parameter '{parameter.Definition?.Name}' is read-only on element {update.ElementId}.");
             }
 
+            var before = GetElementDetails.DescribeParameter(doc, parameter, parameter.Definition?.Name ?? "", false);
             bool accepted = parameter.StorageType switch
             {
                 StorageType.String => parameter.Set(ValueAsString(update.Value)),
@@ -183,36 +141,28 @@ namespace RevitBridge.Tools
                     return SetElementName(element, update);
                 throw new InvalidOperationException($"Revit rejected the value for '{parameter.Definition?.Name}' on element {update.ElementId} (Parameter.Set returned false).");
             }
-            return DescribeNewValue(parameter) ?? ValueAsString(update.Value);
+            return new ValueChange(DescribeNewValue(parameter) ?? ValueAsString(update.Value), before,
+                GetElementDetails.DescribeParameter(doc, parameter, parameter.Definition?.Name ?? "", false));
         }
 
         /// <summary>Rename fallback: the Element.Name property setter.</summary>
-        private static string SetElementName(Element element, Update update)
+        private static ValueChange SetElementName(Element element, Update update)
         {
             string name = ValueAsString(update.Value);
             if (string.IsNullOrWhiteSpace(name))
                 throw new InvalidOperationException("Renaming needs a non-empty string value.");
-            element.Name = name;
-            return name;
+            var before = new { value = element.Name, displayValue = element.Name, storageType = "String" };
+            ElementNames.Assign(element, name);
+            return new ValueChange(name, before, new { value = element.Name, displayValue = element.Name, storageType = "String" });
         }
 
+        /// <summary>
+        /// Shared resolution policy (inv:parameter-ambiguity): a display name matching several
+        /// parameters on the element fails this update with the candidates' exact identities
+        /// instead of writing to an arbitrary one. Missing stays null.
+        /// </summary>
         private static Parameter? FindParameter(Element element, Update update)
-        {
-            if (update.BuiltIn is { } builtIn)
-                return element.get_Parameter(builtIn);
-            if (update.SharedGuid is { } guid)
-                return element.get_Parameter(guid);
-
-            var direct = element.LookupParameter(update.ParameterInput);
-            if (direct != null)
-                return direct;
-            foreach (Parameter parameter in element.Parameters)
-            {
-                if (string.Equals(parameter.Definition?.Name, update.ParameterInput, StringComparison.OrdinalIgnoreCase))
-                    return parameter;
-            }
-            return null;
-        }
+            => ParameterResolver.FindSingle(element, new ParameterReference(update.ParameterInput, update.BuiltIn, update.SharedGuid));
 
         private static string? DescribeNewValue(Parameter parameter)
         {
@@ -354,26 +304,7 @@ namespace RevitBridge.Tools
                 if (!item.TryGetProperty("value", out var value))
                     throw new ArgumentException($"The update for element {elementId} ('{parameterInput}') needs a value.");
 
-                BuiltInParameter? builtIn = null;
-                Guid? sharedGuid = null;
-                if (parameterInput.StartsWith("guid:", StringComparison.OrdinalIgnoreCase))
-                {
-                    sharedGuid = Guid.TryParse(parameterInput["guid:".Length..], out var guid)
-                        ? guid
-                        : throw new ArgumentException($"Invalid shared parameter guid: {parameterInput}");
-                }
-                else
-                {
-                    string enumName = parameterInput.StartsWith("BuiltInParameter.", StringComparison.OrdinalIgnoreCase)
-                        ? parameterInput["BuiltInParameter.".Length..]
-                        : parameterInput;
-                    // 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(parameterInput);
 
                 updates.Add(new Update
                 {
@@ -381,8 +312,8 @@ namespace RevitBridge.Tools
                     ParameterInput = parameterInput,
                     Value = value,
                     Unit = JsonArgs.GetString(item, "unit"),
-                    BuiltIn = builtIn,
-                    SharedGuid = sharedGuid,
+                    BuiltIn = reference.BuiltIn,
+                    SharedGuid = reference.SharedGuid,
                 });
             }
 

package/src/Revit/Tools/SpatialBounds.cs

@@ -0,0 +1,30 @@
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed record SpatialBounds(XYZ Min, XYZ Max)
+{
+    public static SpatialBounds? Of(Element element)
+    {
+        var box = element.get_BoundingBox(null);
+        if (box == null) return null;
+        var corners = new List<XYZ>(8);
+        foreach (double x in new[] { box.Min.X, box.Max.X })
+        foreach (double y in new[] { box.Min.Y, box.Max.Y })
+        foreach (double z in new[] { box.Min.Z, box.Max.Z })
+            corners.Add(box.Transform.OfPoint(new XYZ(x, y, z)));
+        return new(new(corners.Min(p => p.X), corners.Min(p => p.Y), corners.Min(p => p.Z)),
+            new(corners.Max(p => p.X), corners.Max(p => p.Y), corners.Max(p => p.Z)));
+    }
+
+    public bool Intersects(SpatialBounds other) => Min.X <= other.Max.X && Max.X >= other.Min.X
+        && Min.Y <= other.Max.Y && Max.Y >= other.Min.Y && Min.Z <= other.Max.Z && Max.Z >= other.Min.Z;
+    public bool Contains(SpatialBounds other) => Min.X <= other.Min.X && Max.X >= other.Max.X
+        && Min.Y <= other.Min.Y && Max.Y >= other.Max.Y && Min.Z <= other.Min.Z && Max.Z >= other.Max.Z;
+    public XYZ Gap(SpatialBounds other) => new(
+        Math.Max(0, Math.Max(Min.X - other.Max.X, other.Min.X - Max.X)),
+        Math.Max(0, Math.Max(Min.Y - other.Max.Y, other.Min.Y - Max.Y)),
+        Math.Max(0, Math.Max(Min.Z - other.Max.Z, other.Min.Z - Max.Z)));
+    public static double[] Coordinates(XYZ p, double scale) => new[] { p.X / scale, p.Y / scale, p.Z / scale };
+    public object Describe(double scale) => new { min = Coordinates(Min, scale), max = Coordinates(Max, scale) };
+}