pi-revit 0.4.0 → 0.5.0

package/src/Revit/Tools/DocumentGuard.cs

@@ -1,64 +1,74 @@
-using System.Text.Json;
-using Autodesk.Revit.DB;
-
-namespace RevitBridge.Tools;
-
-/// <summary>Opaque identity of one open native document in this loaded bridge session.</summary>
-internal static class DocumentGuard
-{
-    private sealed record Identity(Document Document, string Value);
-    private static readonly string Generation = Guid.NewGuid().ToString("N");
-    private static readonly List<Identity> Identities = new();
-
-    public static string GetIdentity(Document document)
-    {
-        if (!document.IsValidObject)
-            throw new ArgumentException("The target document is closed or invalid. Read get_model_overview again.");
-        // Revit can supply multiple managed wrappers for the same native document.
-        // Its documented Equals semantics identify that native document; reference identity cannot.
-        // All accesses happen on the Revit API thread. Pruning avoids retaining closed documents.
-        Identities.RemoveAll(entry => !entry.Document.IsValidObject);
-        var existing = Identities.FirstOrDefault(entry => entry.Document.Equals(document));
-        if (existing != null) return existing.Value;
-        var created = new Identity(document, Generation + ":" + Guid.NewGuid().ToString("N"));
-        Identities.Add(created);
-        return created.Value;
-    }
-
-    public static bool AlwaysRequiresIdentity(string toolName)
-        => toolName is "set_parameters" or "execute_csharp" or "export_documents" or "open_view";
-
-    /// <summary>Must run on the Revit API thread immediately before the tool action.</summary>
-    public static void CheckForTool(JsonElement args, Document document, string toolName, bool writes = false)
-    {
-        bool required = writes || AlwaysRequiresIdentity(toolName)
-            || (toolName == "manage_selection"
-                && (!string.Equals((JsonArgs.GetString(args, "action") ?? "get").Trim(), "get", StringComparison.OrdinalIgnoreCase)
-                    || JsonArgs.GetBool(args, "isolate_in_view", false)));
-        if (required && !args.TryGetProperty("expected_document_id", out _))
-            throw new ArgumentException("expected_document_id is required for this operation. Read project.documentId from get_model_overview for the intended open document and pass it unchanged. A title alone cannot identify a document. No action was performed.");
-        CheckExpectedDocument(args, document);
-    }
-
-    public static void CheckExpectedDocument(JsonElement args, Document document)
-    {
-        if (args.TryGetProperty("expected_document_id", out var id))
-        {
-            if (id.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(id.GetString()))
-                throw new ArgumentException("expected_document_id must be a non-empty identity from get_model_overview. No action was performed.");
-            if (!string.Equals(id.GetString(), GetIdentity(document), StringComparison.Ordinal))
-                throw new ArgumentException($"The active document '{document.Title}' is not the exact open document this call expected, or that identity is stale after reopening/restarting. No action was performed. Activate the intended document and read get_model_overview again.");
-        }
-
-        // Retained as an additional human-readable check, never as a substitute for identity.
-        string? expected = JsonArgs.GetString(args, "expected_document");
-        if (string.IsNullOrWhiteSpace(expected)) return;
-        static string Normalize(string title)
-        {
-            string value = title.Trim();
-            return value.EndsWith(".rvt", StringComparison.OrdinalIgnoreCase) ? value[..^4] : value;
-        }
-        if (!string.Equals(Normalize(expected), Normalize(document.Title), StringComparison.OrdinalIgnoreCase))
-            throw new ArgumentException($"Active document is '{document.Title}' but this call expected title '{expected}'. No action was performed. Read get_model_overview for the intended document.");
-    }
-}
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+/// <summary>Opaque identity of one open native document in this loaded bridge session.</summary>
+internal static class DocumentGuard
+{
+    private sealed record Identity(Document Document, string Value);
+    private static readonly string Generation = Guid.NewGuid().ToString("N");
+    private static readonly List<Identity> Identities = new();
+
+    public static string GetIdentity(Document document)
+    {
+        if (!document.IsValidObject)
+            throw new ArgumentException("The target document is closed or invalid. Read get_model_overview again.");
+        // Revit can supply multiple managed wrappers for the same native document.
+        // Its documented Equals semantics identify that native document; reference identity cannot.
+        // All accesses happen on the Revit API thread. Pruning avoids retaining closed documents.
+        Identities.RemoveAll(entry => !entry.Document.IsValidObject);
+        var existing = Identities.FirstOrDefault(entry => entry.Document.Equals(document));
+        if (existing != null) return existing.Value;
+        var created = new Identity(document, Generation + ":" + Guid.NewGuid().ToString("N"));
+        Identities.Add(created);
+        return created.Value;
+    }
+
+    public static bool AlwaysRequiresIdentity(string toolName)
+        => toolName is "set_parameters" or "execute_csharp" or "export_documents" or "open_view";
+
+    /// <summary>Project or family: the kind of the active document, as tools declare it.</summary>
+    public static string KindOf(Document document) => document.IsFamilyDocument ? DocumentKind.Family : DocumentKind.Project;
+
+    /// <summary>Refuse a tool in a document kind it does not declare, before it runs (inv:document-kind-declared).</summary>
+    public static void CheckKind(ITool tool, Document document)
+    {
+        if (DocumentKind.Refusal(tool.Name, tool.DocumentKinds, KindOf(document), document.Title) is { } refusal)
+            throw new ArgumentException(refusal);
+    }
+
+    /// <summary>Must run on the Revit API thread immediately before the tool action.</summary>
+    public static void CheckForTool(JsonElement args, Document document, string toolName, bool writes = false)
+    {
+        bool required = writes || AlwaysRequiresIdentity(toolName)
+            || (toolName == "manage_selection"
+                && (!string.Equals((JsonArgs.GetString(args, "action") ?? "get").Trim(), "get", StringComparison.OrdinalIgnoreCase)
+                    || JsonArgs.GetBool(args, "isolate_in_view", false)));
+        if (required && !args.TryGetProperty("expected_document_id", out _))
+            throw new ArgumentException("expected_document_id is required for this operation. Read project.documentId from get_model_overview for the intended open document and pass it unchanged. A title alone cannot identify a document. No action was performed.");
+        CheckExpectedDocument(args, document);
+    }
+
+    public static void CheckExpectedDocument(JsonElement args, Document document)
+    {
+        if (args.TryGetProperty("expected_document_id", out var id))
+        {
+            if (id.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(id.GetString()))
+                throw new ArgumentException("expected_document_id must be a non-empty identity from get_model_overview. No action was performed.");
+            if (!string.Equals(id.GetString(), GetIdentity(document), StringComparison.Ordinal))
+                throw new ArgumentException($"The active document '{document.Title}' is not the exact open document this call expected, or that identity is stale after reopening/restarting. No action was performed. Activate the intended document and read get_model_overview again.");
+        }
+
+        // Retained as an additional human-readable check, never as a substitute for identity.
+        string? expected = JsonArgs.GetString(args, "expected_document");
+        if (string.IsNullOrWhiteSpace(expected)) return;
+        static string Normalize(string title)
+        {
+            string value = title.Trim();
+            return value.EndsWith(".rvt", StringComparison.OrdinalIgnoreCase) ? value[..^4] : value;
+        }
+        if (!string.Equals(Normalize(expected), Normalize(document.Title), StringComparison.OrdinalIgnoreCase))
+            throw new ArgumentException($"Active document is '{document.Title}' but this call expected title '{expected}'. No action was performed. Read get_model_overview for the intended document.");
+    }
+}

package/src/Revit/Tools/ElementNames.cs

@@ -0,0 +1,103 @@
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools
+{
+    /// <summary>
+    /// The one place a tool assigns a name or sheet number (inv:existing-objects-not-reused).
+    /// A name another object of the same kind already uses is rejected before Revit is asked,
+    /// with the existing object's identity in the failure, so the caller learns that the object
+    /// predates this call instead of silently reusing or editing it. There is deliberately no
+    /// "reuse" option: reusing someone else's object needs the user's decision, after which the
+    /// caller works with that object's ID directly. The gate in check-tool-documentation.mjs
+    /// rejects any other Name or SheetNumber assignment in a tool.
+    /// </summary>
+    internal static class ElementNames
+    {
+        public const string CollisionKey = "name_collision";
+
+        /// <summary>Rename element, or fail with the colliding object's identity.</summary>
+        public static void Assign(Element element, string name)
+        {
+            if (string.IsNullOrWhiteSpace(name)) throw new ArgumentException("name must be nonempty.");
+            if (element.Name == name) return;
+            if (RequiresUniqueName(element) && FindSameKind(element, name) is { } existing) throw Collision(element, existing, "name", name);
+            element.Name = name;
+        }
+
+        /// <summary>
+        /// Kinds whose names Revit keeps unique. Sheets (identified by number), rooms and other
+        /// objects may legitimately share a name, so they are not checked here.
+        /// </summary>
+        public static bool RequiresUniqueName(Element element) =>
+            element is (View and not ViewSheet) or Level or Grid or ElementType or Material or ParameterFilterElement;
+
+        /// <summary>Set a sheet number, or fail with the sheet that already has it.</summary>
+        public static void AssignSheetNumber(ViewSheet sheet, string number)
+        {
+            if (string.IsNullOrWhiteSpace(number)) throw new ArgumentException("number must be nonempty.");
+            if (sheet.SheetNumber == number) return;
+            var existing = new FilteredElementCollector(sheet.Document).OfClass(typeof(ViewSheet)).Cast<ViewSheet>()
+                .FirstOrDefault(other => other.Id != sheet.Id && other.SheetNumber == number);
+            if (existing != null) throw Collision(sheet, existing, "sheet number", number);
+            sheet.SheetNumber = number;
+        }
+
+        /// <summary>Create a family type in a family document, or fail when the name is taken.</summary>
+        public static FamilyType NewFamilyType(FamilyManager manager, string name)
+        {
+            EnsureFamilyTypeFree(manager, name);
+            return manager.NewType(name);
+        }
+
+        /// <summary>Rename the current family type, or fail when another type has the name.</summary>
+        public static void RenameCurrentFamilyType(FamilyManager manager, string name)
+        {
+            if (manager.CurrentType?.Name == name) return;
+            EnsureFamilyTypeFree(manager, name);
+            manager.RenameCurrentType(name);
+        }
+
+        /// <summary>Family types are not elements and have no ID; the collision names the type instead.</summary>
+        private static void EnsureFamilyTypeFree(FamilyManager manager, string name)
+        {
+            if (string.IsNullOrWhiteSpace(name)) throw new ArgumentException("name must be nonempty.");
+            if (!manager.Types.Cast<FamilyType>().Any(type => type.Name == name)) return;
+            var error = new ArgumentException(Message("family type", "name", name, null));
+            error.Data[CollisionKey] = new Dictionary<string, object?> { ["existing_id"] = null, ["kind"] = "family type", ["name"] = name };
+            throw error;
+        }
+
+        /// <summary>
+        /// An object of the same kind with this exact name: same class, and for views the same
+        /// view type (a floor plan and a ceiling plan may share a name). Null when the name is free.
+        /// </summary>
+        public static Element? FindSameKind(Element element, string name)
+        {
+            FilteredElementCollector collector;
+            // Some API classes (for example Room) are not native filter classes; Revit's own
+            // uniqueness check still applies to them when the name is assigned.
+            try { collector = new FilteredElementCollector(element.Document).OfClass(element.GetType()); }
+            catch (Autodesk.Revit.Exceptions.ArgumentException) { return null; }
+            return collector.FirstOrDefault(other => other.Id != element.Id && other.Name == name
+                && (element is not View view || (other is View otherView && otherView.ViewType == view.ViewType && otherView.IsTemplate == view.IsTemplate))
+                && (element is not ElementType || other.Category?.Id == element.Category?.Id));
+        }
+
+        /// <summary>Pure message text, shared by every tool and tested offline.</summary>
+        public static string Message(string kind, string what, string value, long? existingId) =>
+            $"A {kind} with the {what} '{value}' already exists{(existingId is long id ? $" (id {id})" : "")}. Nothing was given that {what}. "
+            + "That object existed before this call: do not edit, reuse, replace or delete it unless the user asks. "
+            + "Ask the user, or choose a distinct value and report the collision.";
+
+        private static ArgumentException Collision(Element target, Element existing, string what, string value)
+        {
+            string kind = target is View view ? $"{view.ViewType} view" : target.GetType().Name;
+            var error = new ArgumentException(Message(kind, what, value, existing.Id.Value));
+            error.Data[CollisionKey] = new Dictionary<string, object?>
+            {
+                ["existing_id"] = existing.Id.Value, ["existing_unique_id"] = existing.UniqueId, ["kind"] = kind, [what.Replace(' ', '_')] = value,
+            };
+            return error;
+        }
+    }
+}

package/src/Revit/Tools/ElementQueryScope.cs

@@ -1,27 +1,27 @@
-using System.Text.Json;
-using System.Text.Json.Nodes;
-
-namespace RevitBridge.Tools;
-
-internal static class ElementQueryScope
-{
-    public static JsonObject Schema()
-    {
-        var schema = JsonSerializer.SerializeToNode(new GetElements().ParametersSchema)!.AsObject();
-        foreach (string key in new[] { "count_only", "fields", "offset", "limit", "parameter_names", "include_type_parameters" })
-            schema["properties"]!.AsObject().Remove(key);
-        schema["description"] = "Filter the whole matching scope. Query paging and projections are not supported here.";
-        schema["additionalProperties"] = false;
-        return schema;
-    }
-
-    public static JsonObject Parse(JsonElement args)
-    {
-        var query = args.TryGetProperty("query", out var input) ? JsonNode.Parse(input.GetRawText()) as JsonObject : new JsonObject();
-        if (query == null) throw new ArgumentException("query must be an object.");
-        var allowed = Schema()["properties"]!.AsObject();
-        foreach (var property in query)
-            if (!allowed.ContainsKey(property.Key)) throw new ArgumentException($"query does not support '{property.Key}'. It always uses the whole matching scope.");
-        return query;
-    }
-}
+using System.Text.Json;
+using System.Text.Json.Nodes;
+
+namespace RevitBridge.Tools;
+
+internal static class ElementQueryScope
+{
+    public static JsonObject Schema()
+    {
+        var schema = JsonSerializer.SerializeToNode(new GetElements().ParametersSchema)!.AsObject();
+        foreach (string key in new[] { "count_only", "fields", "offset", "limit", "parameter_names", "include_type_parameters" })
+            schema["properties"]!.AsObject().Remove(key);
+        schema["description"] = "Filter the whole matching scope. Query paging and projections are not supported here.";
+        schema["additionalProperties"] = false;
+        return schema;
+    }
+
+    public static JsonObject Parse(JsonElement args)
+    {
+        var query = args.TryGetProperty("query", out var input) ? JsonNode.Parse(input.GetRawText()) as JsonObject : new JsonObject();
+        if (query == null) throw new ArgumentException("query must be an object.");
+        var allowed = Schema()["properties"]!.AsObject();
+        foreach (var property in query)
+            if (!allowed.ContainsKey(property.Key)) throw new ArgumentException($"query does not support '{property.Key}'. It always uses the whole matching scope.");
+        return query;
+    }
+}

package/src/Revit/Tools/ElementTraits.cs

@@ -0,0 +1,53 @@
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools
+{
+    /// <summary>
+    /// Shared classification of special or system-owned objects (inv:special-objects-flagged).
+    /// Tools never mix these silently into ordinary results: they either flag them here or
+    /// exclude them and count the exclusion. Only non-default traits are emitted, so
+    /// ordinary elements add nothing to a result. New tools reuse this instead of inventing
+    /// their own checks, and new trait kinds are added here once.
+    /// </summary>
+    internal static class ElementTraits
+    {
+        /// <summary>Non-default traits of an element, or null when it has none.</summary>
+        public static Dictionary<string, object>? For(Element element)
+        {
+            var traits = new Dictionary<string, object>();
+            if (element is ScheduleSheetInstance { IsTitleblockRevisionSchedule: true })
+                traits["titleblock_revision_schedule"] = true;
+            if (element is ViewSchedule { IsTitleblockRevisionSchedule: true })
+                traits["titleblock_revision_schedule"] = true;
+            if (element is ViewSheet { IsPlaceholder: true })
+                traits["placeholder_sheet"] = true;
+            if (element is View view)
+            {
+                if (view.IsTemplate)
+                    traits["view_template"] = true;
+                var primary = view.GetPrimaryViewId();
+                if (primary != null && primary != ElementId.InvalidElementId)
+                    traits["dependent_view_of"] = primary.Value;
+            }
+            if (element.GroupId is { } group && group != ElementId.InvalidElementId)
+                traits["group_id"] = group.Value;
+            if (element.DesignOption is { } option)
+                traits["design_option_id"] = option.Id.Value;
+            if (element.Pinned)
+                traits["pinned"] = true;
+            return traits.Count > 0 ? traits : null;
+        }
+
+        /// <summary>
+        /// Kind of a sheet placement. A titleblock revision schedule is part of the titleblock,
+        /// not content someone placed, so it has its own kind and cannot be moved.
+        /// </summary>
+        public static string PlacementKind(Element placement) => placement switch
+        {
+            Viewport => "viewport",
+            ScheduleSheetInstance { IsTitleblockRevisionSchedule: true } => "titleblock_revision_schedule",
+            ScheduleSheetInstance => "schedule",
+            _ => "other",
+        };
+    }
+}

package/src/Revit/Tools/ExecuteCsharp.cs

@@ -20,12 +20,12 @@ namespace RevitBridge.Tools
     /// </summary>
     public sealed class ScriptGlobals
     {
-        internal ScriptGlobals(Document document, UIDocument uiDocument, UIApplication uiApplication, JsonElement inputValues, Action<object?> dump)
+        internal ScriptGlobals(Document document, UIDocument uiDocument, UIApplication uiApplication, JsonElement inputValues, Action<object?> dump)
         {
             doc = document;
             uidoc = uiDocument;
-            uiapp = uiApplication;
-            inputs = inputValues;
+            uiapp = uiApplication;
+            inputs = inputValues;
             Dump = dump;
         }
 
@@ -36,10 +36,10 @@ namespace RevitBridge.Tools
         public UIDocument uidoc { get; }
 
         /// <summary>The Revit UI application.</summary>
-        public UIApplication uiapp { get; }
-
-        /// <summary>Structured inputs supplied separately from the script source.</summary>
-        public JsonElement inputs { get; }
+        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; }
@@ -62,22 +62,31 @@ 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), 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 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
         {
             type = "object",
             properties = new
             {
-                code = new
+                code = new
                 {
                     type = "string",
                     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." },
+                },
+                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",
@@ -87,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.",
         };
 
@@ -102,11 +111,11 @@ namespace RevitBridge.Tools
             DocumentGuard.CheckExpectedDocument(args, doc);
 
             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.");
+            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();
 
@@ -118,7 +127,7 @@ namespace RevitBridge.Tools
             RejectAsyncCode(script.GetCompilation());
 
             var dumps = new List<object?>();
-            var globals = new ScriptGlobals(doc, uidoc, uiapp, inputValues, value =>
+            var globals = new ScriptGlobals(doc, uidoc, uiapp, inputValues, value =>
             {
                 if (dumps.Count < MaxDumps)
                     dumps.Add(Project(value, 0));
@@ -128,9 +137,9 @@ namespace RevitBridge.Tools
 
             using var dialogGuard = new DialogGuard(uiapp);
             using var transaction = new Transaction(doc, "execute_csharp");
-            if (transaction.Start() != TransactionStatus.Started)
-                throw new InvalidOperationException("Unable to start the execute_csharp transaction.");
-            var failureGuard = FailureGuard.Attach(transaction);
+            if (transaction.Start() != TransactionStatus.Started)
+                throw new InvalidOperationException("Unable to start the execute_csharp transaction.");
+            var failureGuard = FailureGuard.Attach(transaction);
 
             object? returnValue;
             string? projectionError = null;
@@ -156,24 +165,24 @@ namespace RevitBridge.Tools
             }
             catch (Exception ex)
             {
-                throw new InvalidOperationException(
-                    FormatRuntimeError(ex, dialogGuard.Suppressed) + " " + FailureGuard.RollBackAndDescribe(transaction), ex);
-            }
-
-            try
-            {
-                var status = transaction.Commit();
-                var finalStatus = transaction.GetStatus();
-                if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
-                    throw new InvalidOperationException($"The execute_csharp commit returned {status}; current transaction status is {finalStatus}.");
-            }
-            catch (Exception ex)
-            {
-                throw new InvalidOperationException(
-                    $"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}"
-                    + failureGuard.DescribeErrors()
-                    + DescribeDialogs(dialogGuard.Suppressed), ex);
-            }
+                throw new InvalidOperationException(
+                    FormatRuntimeError(ex, dialogGuard.Suppressed) + " " + FailureGuard.RollBackAndDescribe(transaction), ex);
+            }
+
+            try
+            {
+                var status = transaction.Commit();
+                var finalStatus = transaction.GetStatus();
+                if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
+                    throw new InvalidOperationException($"The execute_csharp commit returned {status}; current transaction status is {finalStatus}.");
+            }
+            catch (Exception ex)
+            {
+                throw new InvalidOperationException(
+                    $"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}"
+                    + failureGuard.DescribeErrors()
+                    + DescribeDialogs(dialogGuard.Suppressed), ex);
+            }
 
             stopwatch.Stop();
 
@@ -203,8 +212,8 @@ namespace RevitBridge.Tools
                 Assembly.Load("netstandard"),
                 typeof(Enumerable).Assembly,                                // System.Linq
                 typeof(Regex).Assembly,                                     // System.Text.RegularExpressions
-                typeof(Console).Assembly,                                   // System.Console
-                typeof(JsonElement).Assembly,                               // System.Text.Json
+                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")
@@ -251,7 +260,7 @@ namespace RevitBridge.Tools
             string line = TryGetScriptLine(ex) is { } scriptLine ? $" at script line {scriptLine}" : string.Empty;
             string inner = ex.InnerException is { } innerEx ? $" Inner: {innerEx.GetType().Name}: {innerEx.Message}" : string.Empty;
             return $"C# script threw {ex.GetType().Name}{line}: {ex.Message}.{inner}"
-                + DescribeDialogs(suppressedDialogs);
+                + DescribeDialogs(suppressedDialogs);
         }
 
         private static string DescribeDialogs(IReadOnlyList<string> suppressed)