pi-revit 0.4.0 → 0.5.1

package/src/Revit/Tools/GetElements.cs

@@ -20,8 +20,16 @@ namespace RevitBridge.Tools
         private const double Epsilon = 1e-6;
 
         public string Name => "get_elements";
+        public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+        public IReadOnlyList<string> Keywords => new[] { "list", "find", "query", "count", "filter", "search elements", "how many" };
+        public IReadOnlyList<ToolLimit> Limits => new[]
+        {
+            new ToolLimit("Elements inside linked models", "tool", "get_linked_elements"),
+            new ToolLimit("Grouped counts or statistics over a whole scope", "tool", "summarize_elements"),
+            new ToolLimit("Spatial containment or intersection", "tool", "query_spatial_elements"),
+        };
         public string Label => "Get Elements";
-        public string Description => "Query Revit elements: scope by category (display name like 'Walls' or enum name like 'OST_Walls'), element class, level, type id, or active view; filter by parameter rules; paginate with offset/limit or just count with count_only. Returns identity fields and optional parameter_names projections; include_type_parameters also reads the requested values from each type. Rules with an explicit BuiltInParameter or shared GUID can evaluate inside Revit's collector; display-name rules, regex rules, and unsupported quick filters run as a per-element scan. A display name can identify different parameters even within one category or class. Scope queries to reduce the scan, or use an explicit parameter identity when appropriate. Numeric rule values are interpreted in the document's display units for that parameter unless 'unit' is given.";
+        public string Description => "Query Revit elements: scope by category (display name like 'Walls' or enum name like 'OST_Walls'), element class, level, type id, or active view; filter by parameter rules; paginate with offset/limit or just count with count_only. Returns identity fields and optional parameter_names projections; include_type_parameters also reads the requested values from each type. Rules with an explicit BuiltInParameter or shared GUID can evaluate inside Revit's collector; display-name rules, regex rules, and unsupported quick filters run as a per-element scan. A display name can identify different parameters even within one category or class. Scope queries to reduce the scan, or use an explicit parameter identity when appropriate. Numeric rule values are interpreted in the document's display units for that parameter unless 'unit' is given.";
 
         public object ParametersSchema => new
         {
@@ -72,13 +80,13 @@ namespace RevitBridge.Tools
                 level = new { type = "string", description = "Only elements hosted on this level (level name or id)." },
                 type_id = new { type = "integer", description = "Only instances of this element type id (see get_element_types)." },
                 in_active_view = new { type = "boolean", description = "Only elements visible in the active view. Default false." },
-                count_only = new { type = "boolean", description = "Return only total_count, no element rows. Default false." },
-                parameter_names = new
-                {
-                    type = "array", maxItems = 20, items = new { type = "string" },
-                    description = "Optional parameter projections for each returned element: display names, BuiltInParameter names or guid:<GUID>. Every matching parameter is reported, including missing/ambiguous matches. Numeric values use internal units with separate display values. Ignored by count_only.",
-                },
-                include_type_parameters = new { type = "boolean", description = "Also project requested parameters from each element's type. Default false." },
+                count_only = new { type = "boolean", description = "Return only total_count, no element rows. Default false." },
+                parameter_names = new
+                {
+                    type = "array", maxItems = 20, items = new { type = "string" },
+                    description = "Optional parameter projections for each returned element: display names, BuiltInParameter names or guid:<GUID>. Every matching parameter is reported, including missing/ambiguous matches. Numeric values use internal units with separate display values. Ignored by count_only.",
+                },
+                include_type_parameters = new { type = "boolean", description = "Also project requested parameters from each element's type. Default false." },
                 fields = new
                 {
                     type = "array",
@@ -109,10 +117,10 @@ namespace RevitBridge.Tools
                 || string.Equals(JsonArgs.GetString(args, "mode"), "count", StringComparison.OrdinalIgnoreCase);
             int offset = Math.Max(0, JsonArgs.GetInt(args, "offset", 0));
             int limit = Math.Clamp(JsonArgs.GetInt(args, "limit", DefaultLimit), 1, MaxLimit);
-            var fields = ResolveFields(args);
-            var parameterNames = JsonArgs.GetStringArray(args, "parameter_names");
-            if (parameterNames?.Count > 20) throw new ArgumentException("parameter_names allows at most 20 parameter identities.");
-            bool includeTypeParameters = JsonArgs.GetBool(args, "include_type_parameters", false);
+            var fields = ResolveFields(args);
+            var parameterNames = JsonArgs.GetStringArray(args, "parameter_names");
+            if (parameterNames?.Count > 20) throw new ArgumentException("parameter_names allows at most 20 parameter identities.");
+            bool includeTypeParameters = JsonArgs.GetBool(args, "include_type_parameters", false);
 
             ElementId? categoryId = string.IsNullOrWhiteSpace(categoryInput) ? null : CategoryResolver.Resolve(doc, categoryInput);
             Type? elementClass = string.IsNullOrWhiteSpace(classInput) ? null : ElementClassResolver.Resolve(classInput);
@@ -145,7 +153,7 @@ namespace RevitBridge.Tools
                 return collector;
             }
 
-            var (quickFilter, postPredicate, filterWarnings) = BuildParameterFilter(doc, args, CreateBaseCollector);
+            var (quickFilter, postPredicate, filterWarnings, stickyWarnings) = BuildParameterFilter(doc, args, CreateBaseCollector);
 
             FilteredElementCollector CreateCollector()
             {
@@ -158,7 +166,7 @@ namespace RevitBridge.Tools
             if (countOnly && postPredicate is null)
             {
                 int quickCount = CreateCollector().GetElementCount();
-                return CountResult(scope, quickCount, quickCount > 0 ? Array.Empty<string>() : filterWarnings);
+                return CountResult(scope, quickCount, quickCount > 0 ? stickyWarnings : filterWarnings);
             }
 
             var rows = countOnly ? null : new List<Dictionary<string, object?>>(Math.Min(limit, 256));
@@ -167,21 +175,22 @@ namespace RevitBridge.Tools
             {
                 if (postPredicate != null && !postPredicate(element))
                     continue;
-                if (rows != null && total >= offset && rows.Count < limit)
-                {
-                    var row = ElementIdentity.Build(doc, element, fields);
-                    if (parameterNames is { Count: > 0 })
-                        row["parameters"] = GetElementDetails.ProjectParameters(doc, element, parameterNames, includeTypeParameters);
-                    rows.Add(row);
-                }
+                if (rows != null && total >= offset && rows.Count < limit)
+                {
+                    var row = ElementIdentity.Build(doc, element, fields);
+                    if (parameterNames is { Count: > 0 })
+                        row["parameters"] = GetElementDetails.ProjectParameters(doc, element, parameterNames, includeTypeParameters);
+                    rows.Add(row);
+                }
                 total++;
             }
 
-            // A found match proves the query worked: the not-found-on-probes warning is
+            // A found match proves most rules worked: a not-found-on-probes warning is
             // load-bearing only next to a zero, where it distinguishes 'unknown parameter
-            // name' from 'no matching elements'. Beside real matches it is just noise.
+            // name' from 'no matching elements'. is_empty warnings stay, because a missing
+            // parameter can itself produce the matches (inv:missing-not-silent).
             if (total > 0)
-                filterWarnings = Array.Empty<string>();
+                filterWarnings = stickyWarnings;
 
             if (rows is null)
                 return CountResult(scope, total, filterWarnings);
@@ -286,17 +295,18 @@ namespace RevitBridge.Tools
             public required RuleOp Op { get; init; }
             public JsonElement Value { get; init; }
             public string? Unit { get; init; }
+            public required ParameterReference Reference { get; init; }
             public BuiltInParameter? BuiltIn { get; init; }
             public Guid? SharedGuid { get; init; }
             public Regex? CompiledRegex { get; init; }
             public FilterRule? QuickRule { get; set; }
         }
 
-        private static (ElementFilter? Quick, Func<Element, bool>? Post, IReadOnlyList<string> Warnings) BuildParameterFilter(
+        private static (ElementFilter? Quick, Func<Element, bool>? Post, IReadOnlyList<string> Warnings, IReadOnlyList<string> StickyWarnings) BuildParameterFilter(
             Document doc, JsonElement args, Func<FilteredElementCollector> createBaseCollector)
         {
             if (args.ValueKind != JsonValueKind.Object || !args.TryGetProperty("filter", out var filterElement) || filterElement.ValueKind != JsonValueKind.Object)
-                return (null, null, Array.Empty<string>());
+                return (null, null, Array.Empty<string>(), Array.Empty<string>());
 
             bool matchAny = string.Equals(JsonArgs.GetString(filterElement, "match"), "any", StringComparison.OrdinalIgnoreCase);
             if (!filterElement.TryGetProperty("rules", out var rulesElement) || rulesElement.ValueKind != JsonValueKind.Array)
@@ -304,11 +314,11 @@ namespace RevitBridge.Tools
 
             var rules = rulesElement.EnumerateArray().Select(ParseRule).ToList();
             if (rules.Count == 0)
-                return (null, null, Array.Empty<string>());
+                return (null, null, Array.Empty<string>(), Array.Empty<string>());
 
-            // Probe a few in-scope elements for missing-name diagnostics and to find
-            // storage/spec exemplars for explicit parameter identities. A sample must
-            // never turn a display name into an assumed globally uniform identity.
+            // Probe a few in-scope elements for missing-name diagnostics and to find
+            // storage/spec exemplars for explicit parameter identities. A sample must
+            // never turn a display name into an assumed globally uniform identity.
             var probes = new List<Element>(ProbeSize);
             foreach (Element element in createBaseCollector())
             {
@@ -325,13 +335,25 @@ namespace RevitBridge.Tools
             // A warning (not an error: the parameter may exist past the probe window,
             // and is_empty legitimately matches missing parameters) makes the zero honest.
             var warnings = new List<string>();
+            var stickyWarnings = new List<string>();
             if (probes.Count > 0)
             {
                 foreach (var rule in rules)
                 {
                     if (rule.BuiltIn != null || rule.SharedGuid != null)
                         continue;
-                    if (probes.All(probe => FindParameter(probe, rule) is null))
+                    if (probes.All(probe => FindParameter(probe, rule) is null) && rule.Op == RuleOp.IsEmpty)
+                    {
+                        // inv:missing-not-silent: is_empty matches elements that lack the parameter,
+                        // so a misspelled or localized name matches the whole scope. Keep this warning.
+                        string sticky = $"Filter parameter '{rule.ParamInput}' was not found on any of the {probes.Count} probed element(s) in scope. "
+                            + "is_empty also matches elements that do not have the parameter at all, so these results may be elements without it "
+                            + "rather than elements with an empty value. Check the name, or use the language-independent BuiltInParameter name or guid:<GUID> "
+                            + "(get_element_details reports builtInParameter per parameter).";
+                        warnings.Add(sticky);
+                        stickyWarnings.Add(sticky);
+                    }
+                    else if (probes.All(probe => FindParameter(probe, rule) is null))
                         warnings.Add(
                             $"Filter parameter '{rule.ParamInput}' was not found on any of the {probes.Count} probed element(s) in scope, "
                             + "so a 0-match result may mean 'unknown parameter name', not 'no matching elements'. Display names are "
@@ -340,19 +362,19 @@ namespace RevitBridge.Tools
                 }
             }
 
-            foreach (var rule in rules)
-            {
-                if (rule.Op is RuleOp.Regex or RuleOp.IsEmpty or RuleOp.IsNotEmpty)
-                    continue; // always post-scan (missing-parameter semantics)
-                // Category/class scope and unanimous samples do not establish a
-                // uniform parameter identity across later families. Resolve display
-                // names per element; only explicit identities may use a quick rule.
-                if (rule.BuiltIn is null && rule.SharedGuid is null)
-                    continue;
-                var found = probes.Select(probe => FindParameter(probe, rule)).Where(parameter => parameter != null).ToList();
-                if (found.Count == 0)
-                    continue;
-                rule.QuickRule = TryBuildQuickRule(doc, rule, found[0]!);
+            foreach (var rule in rules)
+            {
+                if (rule.Op is RuleOp.Regex or RuleOp.IsEmpty or RuleOp.IsNotEmpty)
+                    continue; // always post-scan (missing-parameter semantics)
+                // Category/class scope and unanimous samples do not establish a
+                // uniform parameter identity across later families. Resolve display
+                // names per element; only explicit identities may use a quick rule.
+                if (rule.BuiltIn is null && rule.SharedGuid is null)
+                    continue;
+                var found = probes.Select(probe => FindParameter(probe, rule)).Where(parameter => parameter != null).ToList();
+                if (found.Count == 0)
+                    continue;
+                rule.QuickRule = TryBuildQuickRule(doc, rule, found[0]!);
             }
 
             var quickRules = rules.Where(rule => rule.QuickRule != null).ToList();
@@ -363,10 +385,10 @@ namespace RevitBridge.Tools
                 // OR with any post-scan rule means everything must be post-scanned: a
                 // collector-level OR filter would wrongly exclude post-rule-only matches.
                 if (postRules.Count > 0)
-                    return (null, element => rules.Any(rule => EvaluatePost(doc, element, rule)), warnings);
+                    return (null, element => rules.Any(rule => EvaluatePost(doc, element, rule)), warnings, stickyWarnings);
 
                 var filters = quickRules.Select(rule => (ElementFilter)new ElementParameterFilter(rule.QuickRule!)).ToList();
-                return (filters.Count == 1 ? filters[0] : new LogicalOrFilter(filters), null, warnings);
+                return (filters.Count == 1 ? filters[0] : new LogicalOrFilter(filters), null, warnings, stickyWarnings);
             }
 
             ElementFilter? quick = quickRules.Count > 0
@@ -375,7 +397,7 @@ namespace RevitBridge.Tools
             Func<Element, bool>? post = postRules.Count > 0
                 ? element => postRules.All(rule => EvaluatePost(doc, element, rule))
                 : null;
-            return (quick, post, warnings);
+            return (quick, post, warnings, stickyWarnings);
         }
 
         private static Rule ParseRule(JsonElement element)
@@ -407,26 +429,7 @@ namespace RevitBridge.Tools
             if (!hasValue && op is not (RuleOp.IsEmpty or RuleOp.IsNotEmpty))
                 throw new ArgumentException($"Filter rule on '{param}' with op {opText} needs a value.");
 
-            BuiltInParameter? builtIn = null;
-            Guid? sharedGuid = null;
-            if (param.StartsWith("guid:", StringComparison.OrdinalIgnoreCase))
-            {
-                sharedGuid = Guid.TryParse(param["guid:".Length..], out var guid)
-                    ? guid
-                    : throw new ArgumentException($"Invalid shared parameter guid: {param}");
-            }
-            else
-            {
-                string enumName = param.StartsWith("BuiltInParameter.", StringComparison.OrdinalIgnoreCase)
-                    ? param["BuiltInParameter.".Length..]
-                    : param;
-                // 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(param);
 
             Regex? regex = null;
             if (op == RuleOp.Regex)
@@ -448,29 +451,15 @@ namespace RevitBridge.Tools
                 Op = op,
                 Value = hasValue ? value : default,
                 Unit = JsonArgs.GetString(element, "unit"),
-                BuiltIn = builtIn,
-                SharedGuid = sharedGuid,
+                Reference = reference,
+                BuiltIn = reference.BuiltIn,
+                SharedGuid = reference.SharedGuid,
                 CompiledRegex = regex,
             };
         }
 
-        private static Parameter? FindParameter(Element element, Rule rule)
-        {
-            if (rule.BuiltIn is { } builtIn)
-                return element.get_Parameter(builtIn);
-            if (rule.SharedGuid is { } guid)
-                return element.get_Parameter(guid);
-
-            var direct = element.LookupParameter(rule.ParamInput);
-            if (direct != null)
-                return direct;
-            foreach (Parameter parameter in element.Parameters)
-            {
-                if (string.Equals(parameter.Definition?.Name, rule.ParamInput, StringComparison.OrdinalIgnoreCase))
-                    return parameter;
-            }
-            return null;
-        }
+        /// <summary>Shared resolution policy: missing is null; an ambiguous display name throws with candidates.</summary>
+        private static Parameter? FindParameter(Element element, Rule rule) => ParameterResolver.FindSingle(element, rule.Reference);
 
         /// <summary>Builds a collector-level FilterRule, or null when the op/storage pair must post-scan.</summary>
         private static FilterRule? TryBuildQuickRule(Document doc, Rule rule, Parameter exemplar)

package/src/Revit/Tools/GetLinkedElements.cs

@@ -1,82 +1,89 @@
-using System.Text.Json;
-using System.Text.Json.Nodes;
-using Autodesk.Revit.DB;
-
-namespace RevitBridge.Tools;
-
-internal sealed class GetLinkedElements : ITool
-{
-    public string Name => "get_linked_elements";
-    public string Label => "Get Linked Elements";
-    public string Tier => "advanced";
-    public string Description => "Query one loaded Revit link with get_elements filters and pagination. Use link_instance_id and expected_linked_document_id from get_linked_models. Returned element IDs belong to the linked document and cannot be passed to host write tools. Optional bounds are axis-aligned in host coordinates, in internal feet. Only direct links are supported; active-view scoping is unavailable.";
-    public object ParametersSchema
-    {
-        get
-        {
-            var schema = JsonSerializer.SerializeToNode(new GetElements().ParametersSchema)!.AsObject();
-            var properties = schema["properties"]!.AsObject();
-            properties.Remove("in_active_view");
-            properties["link_instance_id"] = new JsonObject { ["type"] = "integer" };
-            properties["expected_linked_document_id"] = new JsonObject { ["type"] = "string" };
-            properties["include_bounds"] = new JsonObject { ["type"] = "boolean" };
-            schema["required"] = new JsonArray("link_instance_id", "expected_linked_document_id");
-            return schema;
-        }
-    }
-
-    public object Execute(JsonElement args, ToolContext context)
-    {
-        var host = context.Document ?? throw new NoActiveDocumentException();
-        var id = JsonArgs.GetLong(args, "link_instance_id") ?? throw new ArgumentException("link_instance_id is required.");
-        var link = host.GetElement(new ElementId(id)) as RevitLinkInstance
-            ?? throw new ArgumentException("link_instance_id is not a Revit link instance in the active host document.");
-        var linked = link.GetLinkDocument() ?? throw new ArgumentException("The link is unloaded. Load it in Revit before querying it.");
-        string identity = DocumentGuard.GetIdentity(linked);
-        if (!string.Equals(JsonArgs.GetString(args, "expected_linked_document_id"), identity, StringComparison.Ordinal))
-            throw new ArgumentException("The linked document identity is missing or stale. Read get_linked_models again.");
-        if (JsonArgs.GetBool(args, "in_active_view", false))
-            throw new ArgumentException("in_active_view is not supported for linked queries.");
-
-        var result = (ToolOutput)new GetElements().Execute(args, new ToolContext(linked, null))!;
-        var payload = JsonSerializer.SerializeToNode(result.Payload)!.AsObject();
-        payload["host_document_id"] = DocumentGuard.GetIdentity(host);
-        payload["linked_document_id"] = identity;
-        payload["link_instance_id"] = id;
-        payload["coordinate_unit"] = "ft";
-        if (payload["elements"] is JsonArray elements)
-        {
-            var transform = link.GetTotalTransform();
-            foreach (var row in elements)
-            {
-                var element = linked.GetElement(new ElementId(row!["id"]!.GetValue<long>()));
-                row["unique_id"] = element.UniqueId;
-                row["reference"] = new JsonObject
-                {
-                    ["host_document_id"] = DocumentGuard.GetIdentity(host),
-                    ["link_instance_id"] = id,
-                    ["linked_document_id"] = identity,
-                    ["element_id"] = element.Id.Value,
-                };
-                if (JsonArgs.GetBool(args, "include_bounds", false))
-                    row["host_bounds"] = JsonSerializer.SerializeToNode(HostBounds(element.get_BoundingBox(null), transform));
-            }
-        }
-        return new ToolOutput(payload, result.CompactText);
-    }
-
-    internal static object? HostBounds(BoundingBoxXYZ? box, Transform placement)
-    {
-        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(placement.OfPoint(box.Transform.OfPoint(new XYZ(x, y, z))));
-        return new
-        {
-            min = new[] { corners.Min(p => p.X), corners.Min(p => p.Y), corners.Min(p => p.Z) },
-            max = new[] { corners.Max(p => p.X), corners.Max(p => p.Y), corners.Max(p => p.Z) },
-        };
-    }
-}
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class GetLinkedElements : ITool
+{
+    public string Name => "get_linked_elements";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.ProjectOnly;
+    public IReadOnlyList<string> Keywords => new[] { "linked model", "link", "linked elements", "elements in link", "rvt link", "consultant model" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("Nested links", "api", "RevitLinkInstance.GetLinkDocument on the nested link instances"),
+        new ToolLimit("Editing linked elements", "user", "Edit the linked model itself"),
+    };
+    public string Label => "Get Linked Elements";
+    public string Tier => "advanced";
+    public string Description => "Query one loaded Revit link with get_elements filters and pagination. Use link_instance_id and expected_linked_document_id from get_linked_models. Returned element IDs belong to the linked document and cannot be passed to host write tools. Optional bounds are axis-aligned in host coordinates, in internal feet. Only direct links are supported; active-view scoping is unavailable.";
+    public object ParametersSchema
+    {
+        get
+        {
+            var schema = JsonSerializer.SerializeToNode(new GetElements().ParametersSchema)!.AsObject();
+            var properties = schema["properties"]!.AsObject();
+            properties.Remove("in_active_view");
+            properties["link_instance_id"] = new JsonObject { ["type"] = "integer" };
+            properties["expected_linked_document_id"] = new JsonObject { ["type"] = "string" };
+            properties["include_bounds"] = new JsonObject { ["type"] = "boolean" };
+            schema["required"] = new JsonArray("link_instance_id", "expected_linked_document_id");
+            return schema;
+        }
+    }
+
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var host = context.Document ?? throw new NoActiveDocumentException();
+        var id = JsonArgs.GetLong(args, "link_instance_id") ?? throw new ArgumentException("link_instance_id is required.");
+        var link = host.GetElement(new ElementId(id)) as RevitLinkInstance
+            ?? throw new ArgumentException("link_instance_id is not a Revit link instance in the active host document.");
+        var linked = link.GetLinkDocument() ?? throw new ArgumentException("The link is unloaded. Load it in Revit before querying it.");
+        string identity = DocumentGuard.GetIdentity(linked);
+        if (!string.Equals(JsonArgs.GetString(args, "expected_linked_document_id"), identity, StringComparison.Ordinal))
+            throw new ArgumentException("The linked document identity is missing or stale. Read get_linked_models again.");
+        if (JsonArgs.GetBool(args, "in_active_view", false))
+            throw new ArgumentException("in_active_view is not supported for linked queries.");
+
+        var result = (ToolOutput)new GetElements().Execute(args, new ToolContext(linked, null))!;
+        var payload = JsonSerializer.SerializeToNode(result.Payload)!.AsObject();
+        payload["host_document_id"] = DocumentGuard.GetIdentity(host);
+        payload["linked_document_id"] = identity;
+        payload["link_instance_id"] = id;
+        payload["coordinate_unit"] = "ft";
+        if (payload["elements"] is JsonArray elements)
+        {
+            var transform = link.GetTotalTransform();
+            foreach (var row in elements)
+            {
+                var element = linked.GetElement(new ElementId(row!["id"]!.GetValue<long>()));
+                row["unique_id"] = element.UniqueId;
+                row["reference"] = new JsonObject
+                {
+                    ["host_document_id"] = DocumentGuard.GetIdentity(host),
+                    ["link_instance_id"] = id,
+                    ["linked_document_id"] = identity,
+                    ["element_id"] = element.Id.Value,
+                };
+                if (JsonArgs.GetBool(args, "include_bounds", false))
+                    row["host_bounds"] = JsonSerializer.SerializeToNode(HostBounds(element.get_BoundingBox(null), transform));
+            }
+        }
+        return new ToolOutput(payload, result.CompactText);
+    }
+
+    internal static object? HostBounds(BoundingBoxXYZ? box, Transform placement)
+    {
+        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(placement.OfPoint(box.Transform.OfPoint(new XYZ(x, y, z))));
+        return new
+        {
+            min = new[] { corners.Min(p => p.X), corners.Min(p => p.Y), corners.Min(p => p.Z) },
+            max = new[] { corners.Max(p => p.X), corners.Max(p => p.Y), corners.Max(p => p.Z) },
+        };
+    }
+}

package/src/Revit/Tools/GetLinkedModels.cs

@@ -1,66 +1,73 @@
-using System.Text.Json;
-using Autodesk.Revit.DB;
-
-namespace RevitBridge.Tools;
-
-internal sealed class GetLinkedModels : ITool
-{
-    public string Name => "get_linked_models";
-    public string Label => "Get Linked Models";
-    public string Tier => "advanced";
-    public string Description => "List placed Revit links, including unloaded instances, exact linked document identities and their transforms into host coordinates. Nested links are not traversed. Coordinates and transform origins use internal feet.";
-    public object ParametersSchema => new
-    {
-        type = "object",
-        properties = new
-        {
-            offset = new { type = "integer", minimum = 0 },
-            limit = new { type = "integer", minimum = 1, maximum = 1000 },
-        },
-        required = Array.Empty<string>(),
-    };
-
-    public object Execute(JsonElement args, ToolContext context)
-    {
-        var doc = context.Document ?? throw new NoActiveDocumentException();
-        int offset = Math.Max(0, JsonArgs.GetInt(args, "offset", 0));
-        int limit = Math.Clamp(JsonArgs.GetInt(args, "limit", 100), 1, 1000);
-        var links = new FilteredElementCollector(doc).OfClass(typeof(RevitLinkInstance))
-            .Cast<RevitLinkInstance>().OrderBy(x => x.Id.Value).ToList();
-        var rows = links.Skip(offset).Take(limit).Select(link =>
-        {
-            var linked = link.GetLinkDocument();
-            var transform = link.GetTotalTransform();
-            return new
-            {
-                link_instance_id = link.Id.Value,
-                unique_id = link.UniqueId,
-                name = link.Name,
-                type_id = link.GetTypeId().Value,
-                loaded = linked != null,
-                linked_document_id = linked == null ? null : DocumentGuard.GetIdentity(linked),
-                document_title = linked?.Title,
-                transform = new
-                {
-                    origin = Coordinates(transform.Origin),
-                    basis_x = Coordinates(transform.BasisX),
-                    basis_y = Coordinates(transform.BasisY),
-                    basis_z = Coordinates(transform.BasisZ),
-                },
-            };
-        }).ToArray();
-        return new
-        {
-            document_id = DocumentGuard.GetIdentity(doc),
-            coordinate_unit = "ft",
-            total_count = links.Count,
-            returned_count = rows.Length,
-            offset,
-            has_more = offset + rows.Length < links.Count,
-            next_offset = offset + rows.Length < links.Count ? (int?)(offset + rows.Length) : null,
-            links = rows,
-        };
-    }
-
-    internal static double[] Coordinates(XYZ point) => new[] { point.X, point.Y, point.Z };
-}
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class GetLinkedModels : ITool
+{
+    public string Name => "get_linked_models";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.ProjectOnly;
+    public IReadOnlyList<string> Keywords => new[] { "links", "linked files", "rvt links", "link status", "loaded", "unloaded" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("Loading or reloading an unloaded link", "api", "RevitLinkType.Load"),
+        new ToolLimit("Nested links", "api", "RevitLinkInstance.GetLinkDocument"),
+    };
+    public string Label => "Get Linked Models";
+    public string Tier => "advanced";
+    public string Description => "List placed Revit links, including unloaded instances, exact linked document identities and their transforms into host coordinates. Nested links are not traversed. Coordinates and transform origins use internal feet.";
+    public object ParametersSchema => new
+    {
+        type = "object",
+        properties = new
+        {
+            offset = new { type = "integer", minimum = 0 },
+            limit = new { type = "integer", minimum = 1, maximum = 1000 },
+        },
+        required = Array.Empty<string>(),
+    };
+
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        int offset = Math.Max(0, JsonArgs.GetInt(args, "offset", 0));
+        int limit = Math.Clamp(JsonArgs.GetInt(args, "limit", 100), 1, 1000);
+        var links = new FilteredElementCollector(doc).OfClass(typeof(RevitLinkInstance))
+            .Cast<RevitLinkInstance>().OrderBy(x => x.Id.Value).ToList();
+        var rows = links.Skip(offset).Take(limit).Select(link =>
+        {
+            var linked = link.GetLinkDocument();
+            var transform = link.GetTotalTransform();
+            return new
+            {
+                link_instance_id = link.Id.Value,
+                unique_id = link.UniqueId,
+                name = link.Name,
+                type_id = link.GetTypeId().Value,
+                loaded = linked != null,
+                linked_document_id = linked == null ? null : DocumentGuard.GetIdentity(linked),
+                document_title = linked?.Title,
+                transform = new
+                {
+                    origin = Coordinates(transform.Origin),
+                    basis_x = Coordinates(transform.BasisX),
+                    basis_y = Coordinates(transform.BasisY),
+                    basis_z = Coordinates(transform.BasisZ),
+                },
+            };
+        }).ToArray();
+        return new
+        {
+            document_id = DocumentGuard.GetIdentity(doc),
+            coordinate_unit = "ft",
+            total_count = links.Count,
+            returned_count = rows.Length,
+            offset,
+            has_more = offset + rows.Length < links.Count,
+            next_offset = offset + rows.Length < links.Count ? (int?)(offset + rows.Length) : null,
+            links = rows,
+        };
+    }
+
+    internal static double[] Coordinates(XYZ point) => new[] { point.X, point.Y, point.Z };
+}