pi-revit 0.3.1 → 0.5.0

package/src/Revit/ToolRegistry.cs

@@ -34,6 +34,9 @@ namespace RevitBridge
         /// <summary>True only for tools that mutate the model. Write tools own their transaction.</summary>
         bool Write => false;
 
+        /// <summary>Potential effects, independent of whether this particular call changes anything.</summary>
+        IReadOnlyList<string> Effects => Write ? new[] { "model" } : Array.Empty<string>();
+
         /// <summary>
         /// False only for tools that never touch the Revit API. They skip the bridge's
         /// no-document 409 gate and run directly on the server task instead of the Revit
@@ -44,12 +47,37 @@ namespace RevitBridge
         /// <summary>Activation tier metadata: "core" (default) or "advanced".</summary>
         string Tier => "core";
 
+        /// <summary>
+        /// Document kinds the tool works in: DocumentKind.Both or DocumentKind.ProjectOnly. Every
+        /// bridge tool declares it (the documentation gate requires the declaration); the
+        /// dispatcher refuses other kinds before the tool runs.
+        /// </summary>
+        IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+
         /// <summary>Optional one-line "Available tools" system prompt entry.</summary>
         string? PromptSnippet => null;
 
         /// <summary>Optional system prompt guideline bullets. Each bullet must name the tool.</summary>
         IReadOnlyList<string>? PromptGuidelines => null;
 
+        /// <summary>
+        /// English discovery terms beyond the name and description: synonyms, outcome words
+        /// ("screenshot"), verbs and Revit nouns. Other UI languages are mapped onto these
+        /// terms by discovery alias files, never by translating tool metadata.
+        /// </summary>
+        IReadOnlyList<string> Keywords => Array.Empty<string>();
+
+        /// <summary>Declared capability boundaries, each with an alternative route.</summary>
+        IReadOnlyList<ToolLimit> Limits => Array.Empty<ToolLimit>();
+
+        /// <summary>
+        /// Minimum sufficient check that the requested outcome happened: "reread" (query the
+        /// changed state again), "capture" (inspect an image of the visible result),
+        /// "inspect_output" (open the produced file) or "none" (no durable outcome to check).
+        /// Required when the tool can write or has effects; null for pure reads.
+        /// </summary>
+        string? Verification => null;
+
         /// <summary>
         /// Runs on the Revit API thread (or the server task when RequiresDocument is false).
         /// Returns a ToolOutput or any plain JSON-serializable payload.
@@ -77,6 +105,24 @@ namespace RevitBridge
             registry.Add(new CaptureView());
             registry.Add(new ExportDocuments());
             registry.Add(new GetModelHealth());
+            registry.Add(new GetLinkedModels());
+            registry.Add(new GetLinkedElements());
+            registry.Add(new GetSchedules());
+            registry.Add(new GetElementRelationships());
+            registry.Add(new SummarizeElements());
+            registry.Add(new ManageElementSets());
+            registry.Add(new TransformElements());
+            registry.Add(new Tools.DeleteElements());
+            registry.Add(new ChangeElementTypes());
+            registry.Add(new ManageViews());
+            registry.Add(new ManageSheets());
+            registry.Add(new ManageSheetPlacements());
+            registry.Add(new GetScheduleFields());
+            registry.Add(new ManageSchedules());
+            registry.Add(new CreateTags());
+            registry.Add(new QuerySpatialElements());
+            registry.Add(new MeasureGeometry());
+            registry.Add(new GetModelCoordinates());
             return registry;
         }
 
@@ -103,14 +149,17 @@ namespace RevitBridge
             parameters = DescribeParameters(tool),
             executionMode = "sequential",
             write = tool.Write,
+            effects = tool.Effects,
             requiresDocument = tool.RequiresDocument,
+            documentKinds = tool.DocumentKinds,
+            keywords = tool.Keywords,
+            limits = tool.Limits.Select(limit => new { what = limit.What, alternative = new { kind = limit.Alternative, @ref = limit.Ref } }).ToArray(),
+            verification = tool.Verification,
             promptSnippet = tool.PromptSnippet,
-            promptGuidelines = tool.RequiresDocument
-                ? (tool.PromptGuidelines ?? Array.Empty<string>()).Concat(new[]
-                {
-                    $"{tool.Name}: use project.documentId from get_model_overview as expected_document_id to bind the call to that exact open document. It is required for model writes, open_view, and selection changes; legacy expected_document titles alone are insufficient. Refresh after closing/reopening or restarting Revit."
-                }).ToArray()
-                : tool.PromptGuidelines,
+            // Cross-cutting rules (document identity, manuals, capability and completion
+            // protocols) are stated once by the Pi extension's platform section, not
+            // repeated per tool; guidelines here are tool-specific.
+            promptGuidelines = tool.PromptGuidelines,
         };
 
         private static object DescribeParameters(ITool tool)
@@ -118,12 +167,16 @@ namespace RevitBridge
             if (!tool.RequiresDocument) return tool.ParametersSchema;
             var schema = JsonSerializer.SerializeToNode(tool.ParametersSchema)!.AsObject();
             var properties = schema["properties"]!.AsObject();
+            bool identityRequired = tool.Write || DocumentGuard.AlwaysRequiresIdentity(tool.Name);
+            // The description must agree with requiredness in the same schema.
             properties["expected_document_id"] = new JsonObject
             {
                 ["type"] = "string",
-                ["description"] = "Exact opaque project.documentId from get_model_overview. Required for document writes and UI mutations; optional for reads. Invalid after close/reopen or bridge restart."
+                ["description"] = identityRequired
+                    ? "Required: exact opaque project.documentId from get_model_overview for the intended open document. Invalid after close/reopen or bridge restart."
+                    : "Exact opaque project.documentId from get_model_overview. Not required by the schema for reads, but required at runtime for any model change or UI change this tool performs; when supplied, the call runs only against that document. Invalid after close/reopen or bridge restart."
             };
-            if (DocumentGuard.AlwaysRequiresIdentity(tool.Name))
+            if (identityRequired)
             {
                 var required = schema["required"] as JsonArray ?? new JsonArray();
                 if (!required.Any(x => x?.GetValue<string>() == "expected_document_id")) required.Add("expected_document_id");

package/src/Revit/Tools/CaptureView.cs

@@ -20,6 +20,15 @@ namespace RevitBridge.Tools
         private static readonly TimeSpan CaptureRetention = TimeSpan.FromHours(24);
 
         public string Name => "capture_view";
+        public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+        public IReadOnlyList<string> Keywords => new[] { "screenshot", "image", "png", "picture", "snapshot", "visual check" };
+        public IReadOnlyList<ToolLimit> Limits => new[]
+        {
+            new ToolLimit("Image contents or visual judgement (returns a file path only)", "tool", "read (open the returned PNG)"),
+            new ToolLimit("Deliverable PDF, DWG or IFC files", "tool", "export_documents"),
+        };
+        public string? Verification => "inspect_output";
+        public IReadOnlyList<string> Effects => new[] { "files" };
         public string Label => "Capture View";
         public string Description => "Export a PNG snapshot of a Revit view to a temporary file and return its path — the response contains NO image data; open the returned filePath with the read tool to actually see the image. Defaults to the active view; pass view_id for any other graphical view or sheet (find ids with get_elements, category 'Views' or 'Sheets'). The long image edge is capped at 1568 px. Schedules and view templates cannot be captured.";
         public string Tier => "advanced";

package/src/Revit/Tools/ChangeElementTypes.cs

@@ -0,0 +1,74 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class ChangeElementTypes : ITool
+{
+    /// <summary>Updates whose per-view graphics are scanned; each scan visits every view.</summary>
+    private const int ViewGraphicsLimit = 20;
+    public string Name => "change_element_types";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+    public IReadOnlyList<string> Keywords => new[] { "swap type", "replace type", "change family type", "retype", "switch type" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("Editing a type definition's parameters", "tool", "set_parameters"),
+        new ToolLimit("Creating a new type", "api", "ElementType.Duplicate"),
+        new ToolLimit("Loading a family", "api", "Document.LoadFamily"),
+    };
+    public string? Verification => "reread";
+    public string Label => "Change Element Types";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "Change the type of 1–200 elements using explicit element_id/type_id pairs. Revit validates each type against the target; invalid or pinned targets are reported per update. Some type changes replace the original element: always use resulting_id/unique_id afterward. Each update reports inherited_state: instance values, traits and, for the first 20 updates, views that hide or override the retyped element. Default partial success; atomic=true rolls back all if any update fails. preview=true commit-validates then rolls back, and replacement IDs from previews are temporary. Revit constraints can affect connected/hosted elements; results describe requested targets, not every dependent effect.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            updates = new { type = "array", minItems = 1, maxItems = 200, items = new
+            {
+                type = "object", properties = new { element_id = new { type = "integer", minimum = 1 }, type_id = new { type = "integer", minimum = 1 } },
+                required = new[] { "element_id", "type_id" },
+            } },
+            preview = ModelEditInputs.PreviewSchema,
+            atomic = new { type = "boolean", description = "Roll back the complete batch if any update fails. Default false." },
+        }, required = new[] { "updates" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        if (!args.TryGetProperty("updates", out var updates) || updates.ValueKind != JsonValueKind.Array || updates.GetArrayLength() is < 1 or > 200)
+            throw new ArgumentException("updates must contain 1–200 element_id/type_id pairs.");
+        var seen = new HashSet<long>();
+        var steps = new List<ModelEditBatch.Step>();
+        foreach (var update in updates.EnumerateArray())
+        {
+            long elementId = JsonArgs.GetLong(update, "element_id") ?? 0;
+            long typeId = JsonArgs.GetLong(update, "type_id") ?? 0;
+            if (elementId <= 0 || typeId <= 0 || !seen.Add(elementId)) throw new ArgumentException("Each update needs positive IDs, and element_id must be unique within the batch.");
+            int index = steps.Count;
+            steps.Add(new(new() { ["element_id"] = elementId, ["type_id"] = typeId }, () =>
+            {
+                var element = doc.GetElement(new ElementId(elementId)) ?? throw new ArgumentException($"Element {elementId} not found.");
+                if (element.Pinned) throw new ArgumentException("Target is pinned; it was not unpinned.");
+                var type = doc.GetElement(new ElementId(typeId)) as ElementType ?? throw new ArgumentException($"Type {typeId} not found.");
+                if (!element.IsValidType(type.Id)) throw new ArgumentException($"Type {typeId} is not valid for element {elementId}.");
+                var before = ModelEditInputs.Snapshot(element);
+                var replacement = element.ChangeTypeId(type.Id);
+                doc.Regenerate();
+                var resultId = replacement == ElementId.InvalidElementId ? new ElementId(elementId) : replacement;
+                var result = doc.GetElement(resultId) ?? throw new InvalidOperationException("Changed element could not be resolved.");
+                return new() { ["before"] = before, ["after"] = ModelEditInputs.Snapshot(result),
+                    ["resulting_id"] = result.Id.Value, ["unique_id"] = result.UniqueId,
+                    ["replaced"] = result.Id.Value != elementId,
+                    ["resulting_id_is_temporary"] = result.Id.Value != elementId && JsonArgs.GetBool(args, "preview", false),
+                    // What the retyped element keeps: instance values, traits and per-view graphics (inv:derived-state-reported).
+                    ["inherited_state"] = InheritedState.OfElement(result, result.Id.Value != elementId ? elementId : null, viewGraphics: index < ViewGraphicsLimit) };
+            }));
+        }
+        var batch = ModelEditBatch.Run(doc, Name, args, steps);
+        foreach (var row in batch.Proposed)
+            if (row["replaced"] is true) row["resulting_id_is_temporary"] = true;
+        return batch.Payload;
+    }
+}

package/src/Revit/Tools/ChangeSet.cs

@@ -0,0 +1,39 @@
+namespace RevitBridge.Tools
+{
+    /// <summary>
+    /// Net element changes of one tool call, from Revit's DocumentChanged operations. Pure, so it
+    /// is tested offline. A rolled-back or undone group discards what was recorded before it, so a
+    /// preview (commit inside a rolled-back group) reports no net change.
+    /// </summary>
+    internal sealed class ChangeSet
+    {
+        private readonly HashSet<long> _added = new(), _modified = new(), _deleted = new();
+        public bool Observed { get; private set; }
+        public bool RolledBack { get; private set; }
+        public IReadOnlyCollection<long> Added => _added;
+        public IReadOnlyCollection<long> Modified => _modified;
+        public IReadOnlyCollection<long> Deleted => _deleted;
+
+        public void Record(string operation, IEnumerable<long> added, IEnumerable<long> modified, IEnumerable<long> deleted)
+        {
+            Observed = true;
+            if (operation is not ("TransactionCommitted" or "TransactionRedone"))
+            {
+                // Undo or rollback: everything recorded in this call is no longer a net change.
+                _added.Clear(); _modified.Clear(); _deleted.Clear();
+                RolledBack = true;
+                return;
+            }
+            foreach (var id in added) { _added.Add(id); _deleted.Remove(id); }
+            foreach (var id in modified) if (!_added.Contains(id)) _modified.Add(id);
+            foreach (var id in deleted)
+            {
+                _modified.Remove(id);
+                // Created and deleted within one call leaves nothing behind.
+                if (!_added.Remove(id)) _deleted.Add(id);
+            }
+        }
+
+        public bool IsEmpty => _added.Count == 0 && _modified.Count == 0 && _deleted.Count == 0;
+    }
+}

package/src/Revit/Tools/CreateTags.cs

@@ -0,0 +1,107 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+using Autodesk.Revit.DB.Architecture;
+using Autodesk.Revit.DB.Mechanical;
+
+namespace RevitBridge.Tools;
+
+internal sealed class CreateTags : ITool
+{
+    public string Name => "create_tags";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.ProjectOnly;
+    public IReadOnlyList<string> Keywords => new[] { "tag", "label", "annotate", "annotation", "room tag", "door tag" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("Tagging elements inside linked models", "api", "Reference.CreateLinkReference; IndependentTag.Create"),
+        new ToolLimit("Tagging faces or subelements", "api", "IndependentTag.Create with a face Reference"),
+        new ToolLimit("Creating or loading tag families", "api", "Document.LoadFamily"),
+        new ToolLimit("Text notes, dimensions and other annotation", "api", "TextNote.Create; Creation.ItemFactoryBase.NewDimension"),
+    };
+    public string? Verification => "capture";
+    public string Label => "Create Tags";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "Create up to 100 tags for host-document elements in one explicit view using a loaded tag FamilySymbol. kind=element uses IndependentTag; room, space and area use their corresponding spatial tag APIs. Targets contain element_id and head_position [x,y,z] in document internal coordinates with explicit length unit. head_position always means the tag head, including with leader=true. Spatial tags require a compatible plan view and positions at that spatial element's level; orientation applies only to element tags. Templates, perspective views and unlocked 3D views cannot host independent tags. Default partial success; atomic=true rolls back all on any failure. preview=true commit-validates then rolls back; all proposed tag IDs are temporary. Linked targets and face/subelement references are outside this tool.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            kind = new { type = "string", @enum = new[] { "element", "room", "space", "area" } },
+            view_id = new { type = "integer", minimum = 1 }, tag_type_id = new { type = "integer", minimum = 1 }, unit = ModelEditInputs.LengthUnitSchema,
+            targets = new { type = "array", minItems = 1, maxItems = 100, items = new { type = "object", properties = new { element_id = new { type = "integer", minimum = 1 }, head_position = ModelEditInputs.VectorSchema("Tag head in document internal coordinates, in unit.") }, required = new[] { "element_id", "head_position" } } },
+            leader = new { type = "boolean" }, orientation = new { type = "string", @enum = new[] { "horizontal", "vertical" } },
+            preview = ModelEditInputs.PreviewSchema, atomic = new { type = "boolean" },
+        }, required = new[] { "kind", "view_id", "tag_type_id", "unit", "targets" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        string kind = JsonArgs.GetString(args, "kind") ?? "";
+        if (kind is not ("element" or "room" or "space" or "area")) throw new ArgumentException("Unknown tag kind.");
+        var view = doc.GetElement(new ElementId(JsonArgs.GetLong(args, "view_id") ?? 0)) as View ?? throw new ArgumentException("view_id is not a view.");
+        if (view.IsTemplate || (view is View3D three && (three.IsPerspective || !three.IsLocked))) throw new ArgumentException("Tags require a non-template view; 3D views must be orthographic and locked.");
+        if (kind != "element" && view is not ViewPlan) throw new ArgumentException("Spatial tags require a plan view.");
+        var type = doc.GetElement(new ElementId(JsonArgs.GetLong(args, "tag_type_id") ?? 0)) as FamilySymbol ?? throw new ArgumentException("tag_type_id must identify a loaded tag FamilySymbol.");
+        bool leader = false;
+        if (args.TryGetProperty("leader", out var leaderValue))
+        {
+            if (leaderValue.ValueKind is not (JsonValueKind.True or JsonValueKind.False)) throw new ArgumentException("leader must be boolean.");
+            leader = leaderValue.GetBoolean();
+        }
+        if (kind != "element" && args.TryGetProperty("orientation", out _)) throw new ArgumentException("orientation applies only to element tags.");
+        var orientation = (JsonArgs.GetString(args, "orientation") ?? "horizontal") switch
+        {
+            "horizontal" => TagOrientation.Horizontal, "vertical" => TagOrientation.Vertical, _ => throw new ArgumentException("Invalid orientation."),
+        };
+        if (!args.TryGetProperty("targets", out var targets) || targets.ValueKind != JsonValueKind.Array || targets.GetArrayLength() is < 1 or > 100) throw new ArgumentException("targets must contain 1–100 tag requests.");
+        double scale = ModelEditInputs.LengthScale(args);
+        var steps = new List<ModelEditBatch.Step>();
+        foreach (var input in targets.EnumerateArray())
+        {
+            if (input.ValueKind != JsonValueKind.Object) throw new ArgumentException("Each target must be an object.");
+            long id = JsonArgs.GetLong(input, "element_id") ?? 0;
+            if (id <= 0) throw new ArgumentException("Target element_id must be positive.");
+            var point = ModelEditInputs.Vector(input, "head_position").Multiply(scale);
+            steps.Add(new(new() { ["element_id"] = id }, () =>
+            {
+                var element = doc.GetElement(new ElementId(id)) ?? throw new ArgumentException($"Element {id} not found.");
+                if (!type.IsActive) { type.Activate(); doc.Regenerate(); }
+                Element tag;
+                if (kind == "element")
+                {
+                    var independent = IndependentTag.Create(doc, type.Id, view.Id, new Reference(element), false, orientation, point);
+                    independent.HasLeader = leader;
+                    independent.TagHeadPosition = point;
+                    tag = independent;
+                }
+                else
+                {
+                    if (element.Location is not LocationPoint location || view.GenLevel == null || element.LevelId != view.GenLevel.Id)
+                        throw new ArgumentException("A spatial tag target must be placed on the plan view's level.");
+                    var anchor = new UV(location.Point.X, location.Point.Y);
+                    SpatialElementTag spatial = kind switch
+                    {
+                        "room" when element is Room => doc.Create.NewRoomTag(new LinkElementId(element.Id), anchor, view.Id),
+                        "space" when element is Space space => doc.Create.NewSpaceTag(space, anchor, view),
+                        "area" when element is Area area => doc.Create.NewAreaTag((ViewPlan)view, area, anchor),
+                        _ => throw new ArgumentException($"Element {id} does not match kind {kind}."),
+                    };
+                    if (!spatial.IsValidType(type.Id)) throw new ArgumentException("Tag type does not match the spatial tag category.");
+                    var replacement = spatial.ChangeTypeId(type.Id);
+                    if (replacement != ElementId.InvalidElementId) spatial = (SpatialElementTag)doc.GetElement(replacement);
+                    spatial.HasLeader = leader; spatial.TagHeadPosition = point;
+                    tag = spatial;
+                }
+                doc.Regenerate();
+                var actual = tag is IndependentTag independentResult ? independentResult.TagHeadPosition : ((SpatialElementTag)tag).TagHeadPosition;
+                return new() { ["tag_id"] = tag.Id.Value, ["unique_id"] = tag.UniqueId, ["tag_type_id"] = tag.GetTypeId().Value, ["view_id"] = tag.OwnerViewId.Value,
+                    ["kind"] = kind, ["head_position"] = new[] { actual.X, actual.Y, actual.Z }, ["unit"] = "feet", ["leader"] = leader, ["id_is_temporary"] = false,
+                    // A retyped spatial tag may be replaced by a new element (inv:derived-state-reported).
+                    ["inherited_state"] = InheritedState.OfElement(tag, null) };
+            }));
+        }
+        var batch = ModelEditBatch.Run(doc, Name, args, steps);
+        foreach (var row in batch.Proposed) row["id_is_temporary"] = true;
+        return batch.Payload;
+    }
+}

package/src/Revit/Tools/DeleteElements.cs

@@ -0,0 +1,53 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class DeleteElements : ITool
+{
+    public string Name => "delete_elements";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+    public IReadOnlyList<string> Keywords => new[] { "remove", "erase", "cleanup", "delete view", "delete sheet" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("Pinned elements (rejected, never unpinned automatically)", "user", "Confirm unpinning (Element.Pinned) first"),
+        new ToolLimit("Elements inside linked models", "user", "Edit the linked model itself"),
+        new ToolLimit("One-step purge of unused types", "tool", "get_element_types with include_instance_count, then delete_elements"),
+    };
+    public string? Verification => "reread";
+    public string Label => "Delete Elements";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "Delete 1–200 explicitly selected elements in one atomic step, returning the full set of IDs returned by Revit's deletion API, including dependents. Use preview=true to inspect that set with commit validation and confirmed rollback. Optional expected_deleted_ids rejects a changed deletion set before commit; pass the full preview set to bind a later deletion to that set. Pinned requested elements are rejected. At most 10,000 deleted IDs are permitted; a larger cascade rolls back. Returned IDs include dependencies removed by Document.Delete, not a complete audit of surviving elements modified by Revit.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            element_ids = ModelEditInputs.IdsSchema,
+            preview = ModelEditInputs.PreviewSchema,
+            expected_deleted_ids = new { type = "array", minItems = 1, maxItems = 10000, uniqueItems = true, items = new { type = "integer", minimum = 1 }, description = "Exact full deleted_ids set from a previous preview; mismatches roll back." },
+        }, required = new[] { "element_ids" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        var ids = ModelEditInputs.Ids(args);
+        List<long>? expected = args.TryGetProperty("expected_deleted_ids", out _) ? JsonArgs.GetLongArray(args, "expected_deleted_ids") : null;
+        if (expected != null && (expected.Count is < 1 or > 10000 || expected.Any(x => x <= 0) || expected.Distinct().Count() != expected.Count))
+            throw new ArgumentException("expected_deleted_ids must contain 1–10,000 distinct positive IDs.");
+        return ModelEditBatch.Run(doc, Name, args, new[] { new ModelEditBatch.Step(
+            new() { ["element_ids"] = ids.Select(x => x.Value).ToArray() }, () =>
+            {
+                foreach (var id in ids)
+                {
+                    var element = doc.GetElement(id) ?? throw new ArgumentException($"Element {id.Value} not found.");
+                    if (element.Pinned) throw new ArgumentException($"Element {id.Value} is pinned; no elements were unpinned.");
+                }
+                var deleted = doc.Delete(ids).Select(id => id.Value).OrderBy(id => id).ToArray();
+                if (deleted.Length > 10000) throw new ArgumentException("Deletion exceeds the 10,000-ID cascade limit.");
+                if (expected != null && !deleted.ToHashSet().SetEquals(expected)) throw new ArgumentException("The deletion set changed since the preview; deletion was rolled back. Run a fresh preview.");
+                return new() { ["deleted_ids"] = deleted, ["deleted_count"] = deleted.Length,
+                    ["dependent_ids"] = deleted.Except(ids.Select(x => x.Value)).ToArray() };
+            }) }).Payload;
+    }
+}

package/src/Revit/Tools/DocumentGuard.cs

@@ -28,10 +28,20 @@ internal static class DocumentGuard
     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)
+    public static void CheckForTool(JsonElement args, Document document, string toolName, bool writes = false)
     {
-        bool required = AlwaysRequiresIdentity(toolName)
+        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)));

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

@@ -0,0 +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;
+    }
+}

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",
+        };
+    }
+}