pi-revit 0.4.0 → 0.5.0

package/src/Revit/Tools/ModelEditBatch.cs

@@ -1,102 +1,105 @@
-using System.Text.Json;
-using Autodesk.Revit.DB;
-
-namespace RevitBridge.Tools;
-
-/// <summary>Runs model-only edits. Files, UI actions and arbitrary scripts must not use this preview contract.</summary>
-internal static class ModelEditBatch
-{
-    internal sealed record Step(Dictionary<string, object?> Target, Func<Dictionary<string, object?>> Apply);
-
-    internal sealed record Result(bool Committed, bool Preview, bool Atomic, bool CommitValidationPerformed,
-        IReadOnlyList<Dictionary<string, object?>> Succeeded, IReadOnlyList<Dictionary<string, object?>> Proposed,
-        IReadOnlyList<Dictionary<string, object?>> Failed, IReadOnlyList<string> Warnings)
-    {
-        public object Payload => new
-        {
-            updated = Committed ? Succeeded.Count : 0, committed = Committed, preview = Preview, atomic = Atomic,
-            succeeded = Succeeded, proposed = Proposed, failed = Failed, commitWarnings = Warnings,
-            commit_validation_performed = CommitValidationPerformed,
-            validation = Preview ? (CommitValidationPerformed ? "Revit commit validation completed; preview group rollback confirmed." : "Preview group rollback confirmed. Commit-time validation was not performed because the batch was rejected before commit.") : null,
-        };
-    }
-
-    public static Result Run(Document doc, string name, JsonElement args, IReadOnlyList<Step> steps)
-    {
-        foreach (string flag in new[] { "preview", "atomic" })
-            if (args.TryGetProperty(flag, out var value) && value.ValueKind is not (JsonValueKind.True or JsonValueKind.False))
-                throw new ArgumentException($"{flag} must be a boolean; no edits were attempted.");
-        bool preview = JsonArgs.GetBool(args, "preview", false);
-        bool atomic = JsonArgs.GetBool(args, "atomic", false);
-        var accepted = new List<Dictionary<string, object?>>();
-        var failed = new List<Dictionary<string, object?>>();
-        using var group = preview ? new TransactionGroup(doc, name + " preview") : null;
-        using var transaction = new Transaction(doc, name);
-        try
-        {
-            if (group != null && group.Start() != TransactionStatus.Started) throw new InvalidOperationException("Could not start preview transaction group.");
-            if (transaction.Start() != TransactionStatus.Started) throw new InvalidOperationException("Could not start model transaction.");
-            var failures = FailureGuard.Attach(transaction);
-            for (int index = 0; index < steps.Count; index++)
-            {
-                var step = steps[index];
-                using var part = new SubTransaction(doc);
-                if (part.Start() != TransactionStatus.Started) throw new InvalidOperationException("Could not start edit subtransaction.");
-                Dictionary<string, object?> change;
-                try
-                {
-                    change = step.Apply();
-                    if (part.Commit() != TransactionStatus.Committed || part.GetStatus() != TransactionStatus.Committed)
-                        throw new InvalidOperationException("Edit subtransaction did not commit.");
-                }
-                catch (Autodesk.Revit.Exceptions.RegenerationFailedException) { throw; }
-                catch (Exception error)
-                {
-                    if (part.GetStatus() == TransactionStatus.Started) part.RollBack();
-                    if (part.GetStatus() != TransactionStatus.RolledBack)
-                        throw new InvalidOperationException("Edit rollback could not be confirmed; stopping the batch.", error);
-                    var rejection = new Dictionary<string, object?>(step.Target) { ["index"] = index, ["reason"] = error.Message };
-                    failed.Add(rejection);
-                    continue;
-                }
-                var row = new Dictionary<string, object?>(step.Target) { ["index"] = index };
-                foreach (var field in change) row[field.Key] = field.Value;
-                accepted.Add(row);
-            }
-            bool commit = accepted.Count > 0 && !(atomic && failed.Count > 0);
-            if (commit)
-            {
-                var status = transaction.Commit();
-                if (status != TransactionStatus.Committed || transaction.GetStatus() != TransactionStatus.Committed)
-                    throw new InvalidOperationException($"Commit returned {status}; final status {transaction.GetStatus()}." + failures.DescribeErrors());
-            }
-            else
-            {
-                var status = transaction.RollBack();
-                if (status != TransactionStatus.RolledBack || transaction.GetStatus() != TransactionStatus.RolledBack)
-                    throw new InvalidOperationException("Batch rollback could not be confirmed.");
-            }
-            if (group != null) RollBackGroup(group);
-            bool committed = commit && !preview;
-            return new Result(committed, preview, atomic, commit,
-                committed ? accepted : new List<Dictionary<string, object?>>(),
-                committed ? new List<Dictionary<string, object?>>() : accepted, failed, failures.Warnings);
-        }
-        catch (Exception error)
-        {
-            string cleanup = FailureGuard.RollBackAndDescribe(transaction);
-            if (group != null)
-            {
-                try { RollBackGroup(group); cleanup += " Preview group rollback confirmed."; }
-                catch (Exception rollback) { cleanup += " Preview group rollback not confirmed: " + rollback.Message; }
-            }
-            throw new InvalidOperationException(error.Message + " " + cleanup, error);
-        }
-    }
-
-    private static void RollBackGroup(TransactionGroup group)
-    {
-        if (group.GetStatus() == TransactionStatus.Started) group.RollBack();
-        if (group.GetStatus() != TransactionStatus.RolledBack) throw new InvalidOperationException($"Preview group status is {group.GetStatus()}.");
-    }
-}
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+/// <summary>Runs model-only edits. Files, UI actions and arbitrary scripts must not use this preview contract.</summary>
+internal static class ModelEditBatch
+{
+    internal sealed record Step(Dictionary<string, object?> Target, Func<Dictionary<string, object?>> Apply);
+
+    internal sealed record Result(bool Committed, bool Preview, bool Atomic, bool CommitValidationPerformed,
+        IReadOnlyList<Dictionary<string, object?>> Succeeded, IReadOnlyList<Dictionary<string, object?>> Proposed,
+        IReadOnlyList<Dictionary<string, object?>> Failed, IReadOnlyList<string> Warnings)
+    {
+        public object Payload => new
+        {
+            updated = Committed ? Succeeded.Count : 0, committed = Committed, preview = Preview, atomic = Atomic,
+            succeeded = Succeeded, proposed = Proposed, failed = Failed, commitWarnings = Warnings,
+            commit_validation_performed = CommitValidationPerformed,
+            validation = Preview ? (CommitValidationPerformed ? "Revit commit validation completed; preview group rollback confirmed." : "Preview group rollback confirmed. Commit-time validation was not performed because the batch was rejected before commit.") : null,
+        };
+    }
+
+    public static Result Run(Document doc, string name, JsonElement args, IReadOnlyList<Step> steps)
+    {
+        foreach (string flag in new[] { "preview", "atomic" })
+            if (args.TryGetProperty(flag, out var value) && value.ValueKind is not (JsonValueKind.True or JsonValueKind.False))
+                throw new ArgumentException($"{flag} must be a boolean; no edits were attempted.");
+        bool preview = JsonArgs.GetBool(args, "preview", false);
+        bool atomic = JsonArgs.GetBool(args, "atomic", false);
+        var accepted = new List<Dictionary<string, object?>>();
+        var failed = new List<Dictionary<string, object?>>();
+        using var group = preview ? new TransactionGroup(doc, name + " preview") : null;
+        using var transaction = new Transaction(doc, name);
+        try
+        {
+            if (group != null && group.Start() != TransactionStatus.Started) throw new InvalidOperationException("Could not start preview transaction group.");
+            if (transaction.Start() != TransactionStatus.Started) throw new InvalidOperationException("Could not start model transaction.");
+            var failures = FailureGuard.Attach(transaction);
+            for (int index = 0; index < steps.Count; index++)
+            {
+                var step = steps[index];
+                using var part = new SubTransaction(doc);
+                if (part.Start() != TransactionStatus.Started) throw new InvalidOperationException("Could not start edit subtransaction.");
+                Dictionary<string, object?> change;
+                try
+                {
+                    change = step.Apply();
+                    if (part.Commit() != TransactionStatus.Committed || part.GetStatus() != TransactionStatus.Committed)
+                        throw new InvalidOperationException("Edit subtransaction did not commit.");
+                }
+                catch (Autodesk.Revit.Exceptions.RegenerationFailedException) { throw; }
+                catch (Exception error)
+                {
+                    if (part.GetStatus() == TransactionStatus.Started) part.RollBack();
+                    if (part.GetStatus() != TransactionStatus.RolledBack)
+                        throw new InvalidOperationException("Edit rollback could not be confirmed; stopping the batch.", error);
+                    var rejection = new Dictionary<string, object?>(step.Target) { ["index"] = index, ["reason"] = error.Message };
+                    // Structured facts a shared helper attached (for example ElementNames' name_collision).
+                    foreach (System.Collections.DictionaryEntry entry in error.Data)
+                        if (entry.Key is string key && !rejection.ContainsKey(key)) rejection[key] = entry.Value;
+                    failed.Add(rejection);
+                    continue;
+                }
+                var row = new Dictionary<string, object?>(step.Target) { ["index"] = index };
+                foreach (var field in change) row[field.Key] = field.Value;
+                accepted.Add(row);
+            }
+            bool commit = accepted.Count > 0 && !(atomic && failed.Count > 0);
+            if (commit)
+            {
+                var status = transaction.Commit();
+                if (status != TransactionStatus.Committed || transaction.GetStatus() != TransactionStatus.Committed)
+                    throw new InvalidOperationException($"Commit returned {status}; final status {transaction.GetStatus()}." + failures.DescribeErrors());
+            }
+            else
+            {
+                var status = transaction.RollBack();
+                if (status != TransactionStatus.RolledBack || transaction.GetStatus() != TransactionStatus.RolledBack)
+                    throw new InvalidOperationException("Batch rollback could not be confirmed.");
+            }
+            if (group != null) RollBackGroup(group);
+            bool committed = commit && !preview;
+            return new Result(committed, preview, atomic, commit,
+                committed ? accepted : new List<Dictionary<string, object?>>(),
+                committed ? new List<Dictionary<string, object?>>() : accepted, failed, failures.Warnings);
+        }
+        catch (Exception error)
+        {
+            string cleanup = FailureGuard.RollBackAndDescribe(transaction);
+            if (group != null)
+            {
+                try { RollBackGroup(group); cleanup += " Preview group rollback confirmed."; }
+                catch (Exception rollback) { cleanup += " Preview group rollback not confirmed: " + rollback.Message; }
+            }
+            throw new InvalidOperationException(error.Message + " " + cleanup, error);
+        }
+    }
+
+    private static void RollBackGroup(TransactionGroup group)
+    {
+        if (group.GetStatus() == TransactionStatus.Started) group.RollBack();
+        if (group.GetStatus() != TransactionStatus.RolledBack) throw new InvalidOperationException($"Preview group status is {group.GetStatus()}.");
+    }
+}

package/src/Revit/Tools/ModelEditInputs.cs

@@ -1,49 +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 };
-    }
-}
+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,10 +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 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

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