pi-revit 0.4.0 → 0.5.0

package/src/Revit/Tools/SearchApiDocs.cs

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

package/src/Revit/Tools/SetParameters.cs

@@ -18,6 +18,16 @@ namespace RevitBridge.Tools
         private const int MaxUpdates = 200;
 
         public string Name => "set_parameters";
+        public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+        public IReadOnlyList<string> Keywords => new[] { "parameter", "set value", "edit", "change value", "rename", "mark", "comments", "bulk edit", "update" };
+        public IReadOnlyList<ToolLimit> Limits => new[]
+        {
+            new ToolLimit("Changing an element's type", "tool", "change_element_types"),
+            new ToolLimit("Element properties that are not parameters, such as pinned state", "api", "Element.Pinned"),
+            new ToolLimit("Moving or rotating elements", "tool", "transform_elements"),
+            new ToolLimit("Family parameters, family types and formulas in a family document", "api", DocumentKind.FamilyApi),
+        };
+        public string? Verification => "reread";
         public string Label => "Set Parameters";
         public string Description => "Write parameter values on elements — also the home for rename: parameter 'Name' covers levels, views, sheets, types, etc. (falls back to the element's Name property when the Name parameter is read-only). Each update has its own subtransaction inside one model transaction. Default partial success commits valid updates; atomic=true rolls everything back if any update fails. preview=true validates commit inside a transaction group, then rolls the group back. Results include observed per-step before/after values and distinguish succeeded from proposed updates. parameter accepts a display name (Comments, Mark, Name), a BuiltInParameter enum name (e.g. ALL_MODEL_MARK), or guid:<GUID> for a shared parameter; type parameters live on the element type, so pass the type's id. Values are validated against the parameter's storage type; numeric values are interpreted in the document's display units for that parameter unless 'unit' (e.g. millimeters, feet, squareMeters) is given. Revit warnings raised at commit (e.g. duplicate Mark values) are auto-dismissed and listed in commitWarnings — mention them to the user; error-severity failures roll the whole transaction back.";
         public bool Write => true;
@@ -25,10 +35,10 @@ namespace RevitBridge.Tools
         public object ParametersSchema => new
         {
             type = "object",
-            properties = new
-            {
-                preview = new { type = "boolean", description = "Validate edits through Revit commit, then roll back the enclosing transaction group. Returns proposed before/after values; no model changes remain. Default false." },
-                atomic = new { type = "boolean", description = "Roll back all updates if any fails. Default false preserves successful updates. Each update is isolated in a subtransaction." },
+            properties = new
+            {
+                preview = new { type = "boolean", description = "Validate edits through Revit commit, then roll back the enclosing transaction group. Returns proposed before/after values; no model changes remain. Default false." },
+                atomic = new { type = "boolean", description = "Roll back all updates if any fails. Default false preserves successful updates. Each update is isolated in a subtransaction." },
                 updates = new
                 {
                     type = "array",
@@ -62,37 +72,37 @@ namespace RevitBridge.Tools
             "set_parameters defaults to partial success; use atomic=true for all-or-nothing batches and preview=true for commit-validated model rollback. Always inspect committed, proposed and failed.",
         };
 
-        public object? Execute(JsonElement args, ToolContext context)
-        {
-            var doc = context.Document ?? throw new NoActiveDocumentException();
-            DocumentGuard.CheckExpectedDocument(args, doc);
-            var updates = ParseUpdates(args);
-            var steps = updates.Select(update => new ModelEditBatch.Step(
-                new Dictionary<string, object?> { ["id"] = update.ElementId, ["parameter"] = update.ParameterInput },
-                () =>
-                {
-                    var change = Apply(doc, update);
-                    return new Dictionary<string, object?>
-                    {
-                        ["before"] = change.Before, ["after"] = change.After,
-                        ["newDisplayValue"] = change.Display,
-                    };
-                })).ToArray();
-            var result = ModelEditBatch.Run(doc, Name, args, steps);
-            string summary = result.Preview
-                ? $"Preview rolled back: {result.Proposed.Count} proposed update(s), {result.Failed.Count} failure(s)."
-                : result.Committed
-                    ? $"Applied {result.Succeeded.Count} parameter update(s); {result.Failed.Count} failed."
-                    : $"No updates applied; {result.Failed.Count} failed. Batch rolled back.";
-            return new ToolOutput(result.Payload, summary);
-        }
-
+        public object? Execute(JsonElement args, ToolContext context)
+        {
+            var doc = context.Document ?? throw new NoActiveDocumentException();
+            DocumentGuard.CheckExpectedDocument(args, doc);
+            var updates = ParseUpdates(args);
+            var steps = updates.Select(update => new ModelEditBatch.Step(
+                new Dictionary<string, object?> { ["id"] = update.ElementId, ["parameter"] = update.ParameterInput },
+                () =>
+                {
+                    var change = Apply(doc, update);
+                    return new Dictionary<string, object?>
+                    {
+                        ["before"] = change.Before, ["after"] = change.After,
+                        ["newDisplayValue"] = change.Display,
+                    };
+                })).ToArray();
+            var result = ModelEditBatch.Run(doc, Name, args, steps);
+            string summary = result.Preview
+                ? $"Preview rolled back: {result.Proposed.Count} proposed update(s), {result.Failed.Count} failure(s)."
+                : result.Committed
+                    ? $"Applied {result.Succeeded.Count} parameter update(s); {result.Failed.Count} failed."
+                    : $"No updates applied; {result.Failed.Count} failed. Batch rolled back.";
+            return new ToolOutput(result.Payload, summary);
+        }
+
         // ------------------------------------------------------------- application
 
-        private sealed record ValueChange(string? Display, object? Before, object? After);
-
-        /// <summary>Snapshots the concrete parameter or rename target actually written by this step.</summary>
-        private static ValueChange Apply(Document doc, Update update)
+        private sealed record ValueChange(string? Display, object? Before, object? After);
+
+        /// <summary>Snapshots the concrete parameter or rename target actually written by this step.</summary>
+        private static ValueChange Apply(Document doc, Update update)
         {
             var element = doc.GetElement(new ElementId(update.ElementId))
                 ?? throw new InvalidOperationException($"Element {update.ElementId} not found.");
@@ -115,8 +125,8 @@ namespace RevitBridge.Tools
                 throw new InvalidOperationException($"Parameter '{parameter.Definition?.Name}' is read-only on element {update.ElementId}.");
             }
 
-            var before = GetElementDetails.DescribeParameter(doc, parameter, parameter.Definition?.Name ?? "", false);
-            bool accepted = parameter.StorageType switch
+            var before = GetElementDetails.DescribeParameter(doc, parameter, parameter.Definition?.Name ?? "", false);
+            bool accepted = parameter.StorageType switch
             {
                 StorageType.String => parameter.Set(ValueAsString(update.Value)),
                 StorageType.Double => parameter.Set(ToInternalUnits(doc, parameter, RequireDouble(parameter, update.Value), update.Unit)),
@@ -131,38 +141,28 @@ namespace RevitBridge.Tools
                     return SetElementName(element, update);
                 throw new InvalidOperationException($"Revit rejected the value for '{parameter.Definition?.Name}' on element {update.ElementId} (Parameter.Set returned false).");
             }
-            return new ValueChange(DescribeNewValue(parameter) ?? ValueAsString(update.Value), before,
-                GetElementDetails.DescribeParameter(doc, parameter, parameter.Definition?.Name ?? "", false));
+            return new ValueChange(DescribeNewValue(parameter) ?? ValueAsString(update.Value), before,
+                GetElementDetails.DescribeParameter(doc, parameter, parameter.Definition?.Name ?? "", false));
         }
 
         /// <summary>Rename fallback: the Element.Name property setter.</summary>
-        private static ValueChange SetElementName(Element element, Update update)
+        private static ValueChange SetElementName(Element element, Update update)
         {
             string name = ValueAsString(update.Value);
             if (string.IsNullOrWhiteSpace(name))
                 throw new InvalidOperationException("Renaming needs a non-empty string value.");
-            var before = new { value = element.Name, displayValue = element.Name, storageType = "String" };
-            element.Name = name;
-            return new ValueChange(name, before, new { value = element.Name, displayValue = element.Name, storageType = "String" });
+            var before = new { value = element.Name, displayValue = element.Name, storageType = "String" };
+            ElementNames.Assign(element, name);
+            return new ValueChange(name, before, new { value = element.Name, displayValue = element.Name, storageType = "String" });
         }
 
+        /// <summary>
+        /// Shared resolution policy (inv:parameter-ambiguity): a display name matching several
+        /// parameters on the element fails this update with the candidates' exact identities
+        /// instead of writing to an arbitrary one. Missing stays null.
+        /// </summary>
         private static Parameter? FindParameter(Element element, Update update)
-        {
-            if (update.BuiltIn is { } builtIn)
-                return element.get_Parameter(builtIn);
-            if (update.SharedGuid is { } guid)
-                return element.get_Parameter(guid);
-
-            var direct = element.LookupParameter(update.ParameterInput);
-            if (direct != null)
-                return direct;
-            foreach (Parameter parameter in element.Parameters)
-            {
-                if (string.Equals(parameter.Definition?.Name, update.ParameterInput, StringComparison.OrdinalIgnoreCase))
-                    return parameter;
-            }
-            return null;
-        }
+            => ParameterResolver.FindSingle(element, new ParameterReference(update.ParameterInput, update.BuiltIn, update.SharedGuid));
 
         private static string? DescribeNewValue(Parameter parameter)
         {
@@ -304,26 +304,7 @@ namespace RevitBridge.Tools
                 if (!item.TryGetProperty("value", out var value))
                     throw new ArgumentException($"The update for element {elementId} ('{parameterInput}') needs a value.");
 
-                BuiltInParameter? builtIn = null;
-                Guid? sharedGuid = null;
-                if (parameterInput.StartsWith("guid:", StringComparison.OrdinalIgnoreCase))
-                {
-                    sharedGuid = Guid.TryParse(parameterInput["guid:".Length..], out var guid)
-                        ? guid
-                        : throw new ArgumentException($"Invalid shared parameter guid: {parameterInput}");
-                }
-                else
-                {
-                    string enumName = parameterInput.StartsWith("BuiltInParameter.", StringComparison.OrdinalIgnoreCase)
-                        ? parameterInput["BuiltInParameter.".Length..]
-                        : parameterInput;
-                    // BuiltInParameter names are SHOUTY_SNAKE_CASE; require an underscore or
-                    // all-caps so plain display names like "Comments" never collide.
-                    bool looksLikeEnumName = enumName.Length > 0 && char.IsLetter(enumName[0]) && !enumName.Contains(' ')
-                        && (enumName.Contains('_') || enumName.All(c => !char.IsLetter(c) || char.IsUpper(c)));
-                    if (looksLikeEnumName && Enum.TryParse<BuiltInParameter>(enumName, true, out var parsed) && parsed != BuiltInParameter.INVALID)
-                        builtIn = parsed;
-                }
+                var reference = ParameterReference.Parse(parameterInput);
 
                 updates.Add(new Update
                 {
@@ -331,8 +312,8 @@ namespace RevitBridge.Tools
                     ParameterInput = parameterInput,
                     Value = value,
                     Unit = JsonArgs.GetString(item, "unit"),
-                    BuiltIn = builtIn,
-                    SharedGuid = sharedGuid,
+                    BuiltIn = reference.BuiltIn,
+                    SharedGuid = reference.SharedGuid,
                 });
             }
 

package/src/Revit/Tools/SpatialBounds.cs

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

package/src/Revit/Tools/SummarizeElements.cs

@@ -1,87 +1,94 @@
-using System.Text.Json;
-using System.Text.Json.Nodes;
-
-namespace RevitBridge.Tools;
-
-internal sealed class SummarizeElements : ITool
-{
-    private const int MaxElements = 10000;
-    public string Name => "summarize_elements";
-    public string Label => "Summarize Elements";
-    public string Tier => "advanced";
-    public string Description => "Count matching host-model elements grouped by category, type, level or one parameter value. Accepts get_elements category/class/level/type/filter scopes. At most 10,000 matches; narrow larger queries. Parameter grouping uses exact raw values, with a distinct missing-value group. Ambiguous display-name parameters are rejected. Counts cover the entire matching scope, not just the returned groups page.";
-    public object ParametersSchema
-    {
-        get
-        {
-            var query = ElementQueryScope.Schema();
-            return new
-            {
-                type = "object",
-                properties = new
-                {
-                    query,
-                    group_by = new { type = "string", @enum = new[] { "category", "typeName", "levelId", "parameter" } },
-                    parameter = new { type = "string", description = "Required for group_by=parameter. Name, built-in identity or guid:<GUID>." },
-                    type_parameter = new { type = "boolean", description = "Group by the parameter on the element type instead of the instance." },
-                    offset = new { type = "integer", minimum = 0 },
-                    limit = new { type = "integer", minimum = 1, maximum = 500 },
-                },
-                required = new[] { "group_by" },
-            };
-        }
-    }
-
-    public object Execute(JsonElement args, ToolContext context)
-    {
-        string groupBy = JsonArgs.GetString(args, "group_by") ?? "";
-        if (groupBy is not ("category" or "typeName" or "levelId" or "parameter")) throw new ArgumentException("Unknown group_by value.");
-        string? parameter = JsonArgs.GetString(args, "parameter");
-        if (groupBy == "parameter" && string.IsNullOrWhiteSpace(parameter)) throw new ArgumentException("parameter is required for parameter grouping.");
-        bool typeParameter = JsonArgs.GetBool(args, "type_parameter", false);
-        var query = ElementQueryScope.Parse(args);
-        JsonElement RunQuery() => JsonSerializer.SerializeToElement(((ToolOutput)new GetElements().Execute(JsonSerializer.SerializeToElement(query), context)!).Payload);
-        query["count_only"] = true;
-        var countResult = RunQuery();
-        int total = countResult.GetProperty("total_count").GetInt32();
-        object? warnings = countResult.TryGetProperty("warnings", out var queryWarnings) ? queryWarnings.Clone() : null;
-        if (total > MaxElements) throw new ArgumentException($"Query matches {total} elements; narrow the scope to at most {MaxElements}.");
-        query["count_only"] = false;
-        query["limit"] = 1000;
-        if (groupBy == "parameter")
-        {
-            query["parameter_names"] = new JsonArray(parameter);
-            query["include_type_parameters"] = typeParameter;
-        }
-        var counts = new Dictionary<string, (object? Value, bool Missing, int Count)>();
-        for (int position = 0; position < total; position += 1000)
-        {
-            query["offset"] = position;
-            foreach (var row in RunQuery().GetProperty("elements").EnumerateArray())
-            {
-                object? value = null;
-                bool missing = false;
-                if (groupBy == "parameter")
-                {
-                    var projection = row.GetProperty("parameters").EnumerateArray().FirstOrDefault(p => p.GetProperty("isType").GetBoolean() == typeParameter);
-                    missing = projection.ValueKind == JsonValueKind.Undefined || !projection.GetProperty("found").GetBoolean();
-                    if (!missing)
-                    {
-                        if (projection.GetProperty("ambiguous").GetBoolean()) throw new ArgumentException($"Parameter '{parameter}' is ambiguous on element {row.GetProperty("id")}; use a built-in identity or shared GUID.");
-                        value = projection.GetProperty("matches")[0].GetProperty("value").Clone();
-                    }
-                }
-                else if (row.TryGetProperty(groupBy, out var field)) value = field.Clone();
-                string key = (missing ? "missing:" : "value:") + JsonSerializer.Serialize(value);
-                counts[key] = counts.TryGetValue(key, out var previous) ? (value, missing, previous.Count + 1) : (value, missing, 1);
-            }
-        }
-        int offset = Math.Max(0, JsonArgs.GetInt(args, "offset", 0));
-        int limit = Math.Clamp(JsonArgs.GetInt(args, "limit", 100), 1, 500);
-        var groups = counts.OrderByDescending(pair => pair.Value.Count).ThenBy(pair => pair.Key, StringComparer.Ordinal).Skip(offset).Take(limit)
-            .Select(pair => new { value = pair.Value.Value, missing = pair.Value.Missing, count = pair.Value.Count }).ToArray();
-        return new { total_elements = total, total_groups = counts.Count, group_by = groupBy, parameter, type_parameter = typeParameter,
-            numeric_values = "Revit internal units", warnings, offset, returned_count = groups.Length,
-            next_offset = offset + groups.Length < counts.Count ? (int?)(offset + groups.Length) : null, groups };
-    }
-}
+using System.Text.Json;
+using System.Text.Json.Nodes;
+
+namespace RevitBridge.Tools;
+
+internal sealed class SummarizeElements : ITool
+{
+    private const int MaxElements = 10000;
+    public string Name => "summarize_elements";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+    public IReadOnlyList<string> Keywords => new[] { "statistics", "count by", "group by", "breakdown", "totals", "per level", "distribution" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("Linked-model contents", "tool", "get_linked_elements"),
+        new ToolLimit("Scopes above 10,000 elements", "tool", "narrow the query, or get_elements with count_only for a total"),
+    };
+    public string Label => "Summarize Elements";
+    public string Tier => "advanced";
+    public string Description => "Count matching host-model elements grouped by category, type, level or one parameter value. Accepts get_elements category/class/level/type/filter scopes. At most 10,000 matches; narrow larger queries. Parameter grouping uses exact raw values, with a distinct missing-value group. Ambiguous display-name parameters are rejected. Counts cover the entire matching scope, not just the returned groups page.";
+    public object ParametersSchema
+    {
+        get
+        {
+            var query = ElementQueryScope.Schema();
+            return new
+            {
+                type = "object",
+                properties = new
+                {
+                    query,
+                    group_by = new { type = "string", @enum = new[] { "category", "typeName", "levelId", "parameter" } },
+                    parameter = new { type = "string", description = "Required for group_by=parameter. Name, built-in identity or guid:<GUID>." },
+                    type_parameter = new { type = "boolean", description = "Group by the parameter on the element type instead of the instance." },
+                    offset = new { type = "integer", minimum = 0 },
+                    limit = new { type = "integer", minimum = 1, maximum = 500 },
+                },
+                required = new[] { "group_by" },
+            };
+        }
+    }
+
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        string groupBy = JsonArgs.GetString(args, "group_by") ?? "";
+        if (groupBy is not ("category" or "typeName" or "levelId" or "parameter")) throw new ArgumentException("Unknown group_by value.");
+        string? parameter = JsonArgs.GetString(args, "parameter");
+        if (groupBy == "parameter" && string.IsNullOrWhiteSpace(parameter)) throw new ArgumentException("parameter is required for parameter grouping.");
+        bool typeParameter = JsonArgs.GetBool(args, "type_parameter", false);
+        var query = ElementQueryScope.Parse(args);
+        JsonElement RunQuery() => JsonSerializer.SerializeToElement(((ToolOutput)new GetElements().Execute(JsonSerializer.SerializeToElement(query), context)!).Payload);
+        query["count_only"] = true;
+        var countResult = RunQuery();
+        int total = countResult.GetProperty("total_count").GetInt32();
+        object? warnings = countResult.TryGetProperty("warnings", out var queryWarnings) ? queryWarnings.Clone() : null;
+        if (total > MaxElements) throw new ArgumentException($"Query matches {total} elements; narrow the scope to at most {MaxElements}.");
+        query["count_only"] = false;
+        query["limit"] = 1000;
+        if (groupBy == "parameter")
+        {
+            query["parameter_names"] = new JsonArray(parameter);
+            query["include_type_parameters"] = typeParameter;
+        }
+        var counts = new Dictionary<string, (object? Value, bool Missing, int Count)>();
+        for (int position = 0; position < total; position += 1000)
+        {
+            query["offset"] = position;
+            foreach (var row in RunQuery().GetProperty("elements").EnumerateArray())
+            {
+                object? value = null;
+                bool missing = false;
+                if (groupBy == "parameter")
+                {
+                    var projection = row.GetProperty("parameters").EnumerateArray().FirstOrDefault(p => p.GetProperty("isType").GetBoolean() == typeParameter);
+                    missing = projection.ValueKind == JsonValueKind.Undefined || !projection.GetProperty("found").GetBoolean();
+                    if (!missing)
+                    {
+                        if (projection.GetProperty("ambiguous").GetBoolean()) throw new ArgumentException($"Parameter '{parameter}' is ambiguous on element {row.GetProperty("id")}; use a built-in identity or shared GUID.");
+                        value = projection.GetProperty("matches")[0].GetProperty("value").Clone();
+                    }
+                }
+                else if (row.TryGetProperty(groupBy, out var field)) value = field.Clone();
+                string key = (missing ? "missing:" : "value:") + JsonSerializer.Serialize(value);
+                counts[key] = counts.TryGetValue(key, out var previous) ? (value, missing, previous.Count + 1) : (value, missing, 1);
+            }
+        }
+        int offset = Math.Max(0, JsonArgs.GetInt(args, "offset", 0));
+        int limit = Math.Clamp(JsonArgs.GetInt(args, "limit", 100), 1, 500);
+        var groups = counts.OrderByDescending(pair => pair.Value.Count).ThenBy(pair => pair.Key, StringComparer.Ordinal).Skip(offset).Take(limit)
+            .Select(pair => new { value = pair.Value.Value, missing = pair.Value.Missing, count = pair.Value.Count }).ToArray();
+        return new { total_elements = total, total_groups = counts.Count, group_by = groupBy, parameter, type_parameter = typeParameter,
+            numeric_values = "Revit internal units", warnings, offset, returned_count = groups.Length,
+            next_offset = offset + groups.Length < counts.Count ? (int?)(offset + groups.Length) : null, groups };
+    }
+}