pi-revit 0.4.0 → 0.5.0

package/src/Revit/Tools/ExportDocuments.cs

@@ -1,6 +1,6 @@
-using System.IO;
-using System.Security.Cryptography;
-using System.Text;
+using System.IO;
+using System.Security.Cryptography;
+using System.Text;
 using System.Text.Json;
 using Autodesk.Revit.DB;
 
@@ -20,10 +20,18 @@ namespace RevitBridge.Tools
         private const int PngPixelWidth = 2048;
 
         public string Name => "export_documents";
+        public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+        public IReadOnlyList<string> Keywords => new[] { "pdf", "dwg", "ifc", "png", "print", "publish", "plot", "export sheets" };
+        public IReadOnlyList<ToolLimit> Limits => new[]
+        {
+            new ToolLimit("Formats other than PDF, DWG, PNG and IFC", "api", "Document.Export overloads (e.g. DXFExportOptions, NavisworksExportOptions); verify the installed exporter"),
+            new ToolLimit("Printing to a physical printer", "api", "PrintManager"),
+        };
+        public string? Verification => "inspect_output";
         public string Label => "Export Documents";
         public string Description => "Export documents from the open Revit model. format 'pdf'/'dwg'/'png' export the given sheet/view ids to files: pdf combines everything into one file by default (combine=false writes one PDF per sheet/view, named by Revit's naming rule); png renders 2048 px wide; ifc exports the whole model, or just what one given view shows. Files sort themselves per model: with output_dir omitted they land in Documents\\pi-revit\\Models\\<model title>--<identity hash>\\exports, derived from the document being exported (pass output_dir only for a different explicit target); file_name_prefix sets the base file name (default: the document title; Revit appends view/sheet suffixes for multi-file exports). Returns the produced file paths with sizes. Find sheet/view ids with get_elements (category 'Sheets' or 'Views') first.";
-        public bool Write => true;
-        public IReadOnlyList<string> Effects => new[] { "model", "files" };
+        public bool Write => true;
+        public IReadOnlyList<string> Effects => new[] { "model", "files" };
         public string Tier => "advanced";
 
         public object ParametersSchema => new
@@ -89,37 +97,37 @@ namespace RevitBridge.Tools
             // recent (a shared output_dir, another tool writing alongside) does not.
             var before = SnapshotWriteTimes(outputDir);
 
-            IReadOnlyList<string> commitWarnings = Array.Empty<string>();
-            try
-            {
-                switch (format)
-                {
-                    case "pdf": ExportPdf(doc, views, outputDir, baseName, combine); break;
-                    case "dwg": ExportDwg(doc, views, outputDir, baseName); break;
-                    case "png": ExportPng(doc, views, outputDir, baseName); break;
-                    default: commitWarnings = ExportIfc(doc, views, outputDir, baseName); break;
-                }
-            }
-            catch (Exception ex)
-            {
-                // A failed export may already have written some files. A Revit
-                // transaction rollback cannot undo those filesystem changes.
-                string observed;
-                try
-                {
-                    var changed = FindChangedFiles(outputDir, before).ToList();
-                    observed = changed.Count == 0
-                        ? "No changed files were observed."
-                        : $"Observed {changed.Count} new or changed file(s): {string.Join(", ", changed.Take(20))}{(changed.Count > 20 ? " (additional files omitted)" : string.Empty)}.";
-                }
-                catch (Exception scanError)
-                {
-                    observed = $"Could not inspect remaining files: {scanError.Message}.";
-                }
-                throw new InvalidOperationException($"{ex.Message} The export failed; files in '{outputDir}' may be incomplete and were not removed. {observed}", ex);
-            }
-
-            var files = FindChangedFiles(outputDir, before)
+            IReadOnlyList<string> commitWarnings = Array.Empty<string>();
+            try
+            {
+                switch (format)
+                {
+                    case "pdf": ExportPdf(doc, views, outputDir, baseName, combine); break;
+                    case "dwg": ExportDwg(doc, views, outputDir, baseName); break;
+                    case "png": ExportPng(doc, views, outputDir, baseName); break;
+                    default: commitWarnings = ExportIfc(doc, views, outputDir, baseName); break;
+                }
+            }
+            catch (Exception ex)
+            {
+                // A failed export may already have written some files. A Revit
+                // transaction rollback cannot undo those filesystem changes.
+                string observed;
+                try
+                {
+                    var changed = FindChangedFiles(outputDir, before).ToList();
+                    observed = changed.Count == 0
+                        ? "No changed files were observed."
+                        : $"Observed {changed.Count} new or changed file(s): {string.Join(", ", changed.Take(20))}{(changed.Count > 20 ? " (additional files omitted)" : string.Empty)}.";
+                }
+                catch (Exception scanError)
+                {
+                    observed = $"Could not inspect remaining files: {scanError.Message}.";
+                }
+                throw new InvalidOperationException($"{ex.Message} The export failed; files in '{outputDir}' may be incomplete and were not removed. {observed}", ex);
+            }
+
+            var files = FindChangedFiles(outputDir, before)
                 .Select(path => new Dictionary<string, object?>
                 {
                     ["path"] = path,
@@ -130,23 +138,23 @@ namespace RevitBridge.Tools
                 throw new InvalidOperationException($"The {format} export finished but produced no files in {outputDir}.");
 
             string sample = string.Join(", ", files.Take(3).Select(file => Path.GetFileName((string)file["path"]!)));
-            string compact = $"Exported {files.Count} {format.ToUpperInvariant()} file(s) to {outputDir}: {sample}{(files.Count > 3 ? $" (+{files.Count - 3} more)" : string.Empty)}.";
-            if (commitWarnings.Count > 0)
-                compact += $" {commitWarnings.Count} Revit warning(s) auto-dismissed (see commitWarnings).";
+            string compact = $"Exported {files.Count} {format.ToUpperInvariant()} file(s) to {outputDir}: {sample}{(files.Count > 3 ? $" (+{files.Count - 3} more)" : string.Empty)}.";
+            if (commitWarnings.Count > 0)
+                compact += $" {commitWarnings.Count} Revit warning(s) auto-dismissed (see commitWarnings).";
             return new ToolOutput(new
             {
                 format,
                 outputDir,
                 fileCount = files.Count,
-                files,
-                commitWarnings,
-            }, compact);
-        }
-
-        private static IEnumerable<string> FindChangedFiles(string directory, IReadOnlyDictionary<string, DateTime> before)
-            => Directory.GetFiles(directory)
-                .Where(path => !before.TryGetValue(path, out DateTime writtenBefore) || SafeWriteTime(path) != writtenBefore)
-                .OrderBy(path => path, StringComparer.OrdinalIgnoreCase);
+                files,
+                commitWarnings,
+            }, compact);
+        }
+
+        private static IEnumerable<string> FindChangedFiles(string directory, IReadOnlyDictionary<string, DateTime> before)
+            => Directory.GetFiles(directory)
+                .Where(path => !before.TryGetValue(path, out DateTime writtenBefore) || SafeWriteTime(path) != writtenBefore)
+                .OrderBy(path => path, StringComparer.OrdinalIgnoreCase);
 
         /// <summary>path -> last write time for the files already in the output directory.
         /// A file whose time cannot be read is left out, so the export reports it if it
@@ -228,29 +236,29 @@ namespace RevitBridge.Tools
         /// <summary>The IFC exporter writes IFC GUID parameters onto exported elements,
         /// so the Revit API requires a transaction around it — owned here, matching
         /// Revit's own behavior of committing those GUIDs on export.</summary>
-        private static IReadOnlyList<string> ExportIfc(Document doc, List<View> views, string outputDir, string baseName)
+        private static IReadOnlyList<string> ExportIfc(Document doc, List<View> views, string outputDir, string baseName)
         {
             var options = new IFCExportOptions();
             if (views.Count == 1)
                 options.FilterViewId = views[0].Id;
 
             using var transaction = new Transaction(doc, "export_documents: ifc");
-            if (transaction.Start() != TransactionStatus.Started)
-                throw new InvalidOperationException("Unable to start the IFC export transaction.");
-            var failureGuard = FailureGuard.Attach(transaction);
+            if (transaction.Start() != TransactionStatus.Started)
+                throw new InvalidOperationException("Unable to start the IFC export transaction.");
+            var failureGuard = FailureGuard.Attach(transaction);
             try
             {
                 if (!Run(() => doc.Export(outputDir, baseName, options), "IFC"))
                     throw new InvalidOperationException("Revit reported a failed IFC export.");
-                var status = transaction.Commit();
-                var finalStatus = transaction.GetStatus();
-                if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
-                    throw new InvalidOperationException($"The IFC export commit returned {status}; current transaction status is {finalStatus}." + failureGuard.DescribeErrors());
-                return failureGuard.Warnings;
-            }
-            catch (Exception ex)
-            {
-                throw new InvalidOperationException($"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}", ex);
+                var status = transaction.Commit();
+                var finalStatus = transaction.GetStatus();
+                if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
+                    throw new InvalidOperationException($"The IFC export commit returned {status}; current transaction status is {finalStatus}." + failureGuard.DescribeErrors());
+                return failureGuard.Warnings;
+            }
+            catch (Exception ex)
+            {
+                throw new InvalidOperationException($"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}", ex);
             }
         }
 
@@ -311,72 +319,72 @@ namespace RevitBridge.Tools
         }
 
         /// <summary>Per-model folder under the pi-revit workspace:
-        /// Documents\pi-revit\Models\&lt;model title&gt;--&lt;identity hash&gt;.
-        /// Existing title-only folders are left untouched; identity markers are
-        /// diagnostic records, not the mechanism that separates exports.</summary>
-        private static string ModelFolder(Document doc)
+        /// Documents\pi-revit\Models\&lt;model title&gt;--&lt;identity hash&gt;.
+        /// Existing title-only folders are left untouched; identity markers are
+        /// diagnostic records, not the mechanism that separates exports.</summary>
+        private static string ModelFolder(Document doc)
         {
             string workspace = Path.Combine(
                 Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments), "pi-revit");
-            string identity = GetModelIdentity(doc);
-            string folder = Path.Combine(workspace, "Models", GetModelFolderName(doc.Title, identity));
-            Directory.CreateDirectory(folder);
-            TryRecordModelIdentity(folder, doc, identity);
-            return folder;
-        }
-
-        internal static string GetModelFolderName(string title, string identity)
-        {
-            string cleanTitle = SanitizeFileName(string.IsNullOrWhiteSpace(title) ? "untitled" : title);
-            // Bound the default path component, leaving room for the identity and exports.
-            if (cleanTitle.Length > 80)
-                cleanTitle = cleanTitle[..80];
-            string hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(identity))).ToLowerInvariant()[..24];
-            return $"{cleanTitle}--{hash}";
-        }
-
-        // Revit can return different managed wrappers for one open native document.
-        // Document.Equals/GetHashCode identify that open document, unlike reference
-        // equality in ConditionalWeakTable. Closed document entries are pruned below.
-        // Tool execution and this dictionary are confined to the Revit API thread.
-        private static readonly Dictionary<Document, string> OpenDocumentIdentities = new();
-
-        internal static string GetModelIdentity(Document doc)
-        {
-            try
-            {
-                if (doc.IsModelInCloud)
-                {
-                    var path = doc.GetCloudModelPath();
-                    return $"cloud:{path.Region.ToUpperInvariant()}:{path.GetProjectGUID():D}:{path.GetModelGUID():D}";
-                }
-                string pathName = doc.PathName;
-                if (!string.IsNullOrWhiteSpace(pathName))
-                {
-                    // Revit file paths are Windows paths; canonicalize separators,
-                    // relative segments and case. Revit Server identities use RSN URLs.
-                    if (pathName.StartsWith("RSN://", StringComparison.OrdinalIgnoreCase))
-                        return "server:" + pathName.Replace('\\', '/').TrimEnd('/').ToUpperInvariant();
-                    return "file:" + Path.GetFullPath(pathName).Replace('/', '\\').ToUpperInvariant();
-                }
-            }
-            catch
-            {
-                // An unavailable identity must not collapse unrelated documents into
-                // a shared title-only directory. Use the same safe fallback as unsaved docs.
-            }
-            foreach (var closed in OpenDocumentIdentities.Keys.Where(key => !key.IsValidObject).ToList())
-                OpenDocumentIdentities.Remove(closed);
-            if (!OpenDocumentIdentities.TryGetValue(doc, out string? identity))
-                OpenDocumentIdentities[doc] = identity = $"session:{Guid.NewGuid():N}";
-            return identity;
-        }
-
-        private static void TryRecordModelIdentity(string folder, Document doc, string identity)
+            string identity = GetModelIdentity(doc);
+            string folder = Path.Combine(workspace, "Models", GetModelFolderName(doc.Title, identity));
+            Directory.CreateDirectory(folder);
+            TryRecordModelIdentity(folder, doc, identity);
+            return folder;
+        }
+
+        internal static string GetModelFolderName(string title, string identity)
+        {
+            string cleanTitle = SanitizeFileName(string.IsNullOrWhiteSpace(title) ? "untitled" : title);
+            // Bound the default path component, leaving room for the identity and exports.
+            if (cleanTitle.Length > 80)
+                cleanTitle = cleanTitle[..80];
+            string hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(identity))).ToLowerInvariant()[..24];
+            return $"{cleanTitle}--{hash}";
+        }
+
+        // Revit can return different managed wrappers for one open native document.
+        // Document.Equals/GetHashCode identify that open document, unlike reference
+        // equality in ConditionalWeakTable. Closed document entries are pruned below.
+        // Tool execution and this dictionary are confined to the Revit API thread.
+        private static readonly Dictionary<Document, string> OpenDocumentIdentities = new();
+
+        internal static string GetModelIdentity(Document doc)
+        {
+            try
+            {
+                if (doc.IsModelInCloud)
+                {
+                    var path = doc.GetCloudModelPath();
+                    return $"cloud:{path.Region.ToUpperInvariant()}:{path.GetProjectGUID():D}:{path.GetModelGUID():D}";
+                }
+                string pathName = doc.PathName;
+                if (!string.IsNullOrWhiteSpace(pathName))
+                {
+                    // Revit file paths are Windows paths; canonicalize separators,
+                    // relative segments and case. Revit Server identities use RSN URLs.
+                    if (pathName.StartsWith("RSN://", StringComparison.OrdinalIgnoreCase))
+                        return "server:" + pathName.Replace('\\', '/').TrimEnd('/').ToUpperInvariant();
+                    return "file:" + Path.GetFullPath(pathName).Replace('/', '\\').ToUpperInvariant();
+                }
+            }
+            catch
+            {
+                // An unavailable identity must not collapse unrelated documents into
+                // a shared title-only directory. Use the same safe fallback as unsaved docs.
+            }
+            foreach (var closed in OpenDocumentIdentities.Keys.Where(key => !key.IsValidObject).ToList())
+                OpenDocumentIdentities.Remove(closed);
+            if (!OpenDocumentIdentities.TryGetValue(doc, out string? identity))
+                OpenDocumentIdentities[doc] = identity = $"session:{Guid.NewGuid():N}";
+            return identity;
+        }
+
+        private static void TryRecordModelIdentity(string folder, Document doc, string identity)
         {
             try
             {
-                string line = $"{identity}\t{doc.PathName}";
+                string line = $"{identity}\t{doc.PathName}";
                 string marker = Path.Combine(folder, "model.txt");
                 if (!File.Exists(marker) || !File.ReadAllLines(marker).Contains(line))
                     File.AppendAllLines(marker, new[] { line });

package/src/Revit/Tools/GetElementDetails.cs

@@ -9,6 +9,14 @@ namespace RevitBridge.Tools
         private const int MaxIds = 50;
 
         public string Name => "get_element_details";
+        public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+        public IReadOnlyList<string> Keywords => new[] { "parameters", "properties", "inspect", "values", "material", "bounding box", "location" };
+        public IReadOnlyList<ToolLimit> Limits => new[]
+        {
+            new ToolLimit("Listing or filtering elements", "tool", "get_elements"),
+            new ToolLimit("Elements inside linked models", "tool", "get_linked_elements"),
+            new ToolLimit("Exact solid geometry or faces", "api", "Element.Geometry(Options)"),
+        };
         public string Label => "Get Element Details";
         public string Description => "Inspect one or more elements by id: parameter VALUES (name, internal value, formatted displayValue, storage type, display unit where applicable, read-only/shared flags), plus optional type parameters, location (point/curve), bounding box, and materials. Internal numeric values are Revit internal units (feet-based); displayValue is formatted in the document's display units and 'unit' names that display unit. Use get_elements parameter_names to project a small set of values alongside a query.";
 
@@ -36,7 +44,7 @@ namespace RevitBridge.Tools
                     properties = new
                     {
                         parameters = new { type = "boolean", description = "Instance parameter values. Default true." },
-                        type_parameters = new { type = "boolean", description = "Include the element type's parameters, marked isType=true, independently of the instance parameters flag. Default false." },
+                        type_parameters = new { type = "boolean", description = "Include the element type's parameters, marked isType=true, independently of the instance parameters flag. Default false." },
                         location = new { type = "boolean", description = "Location point or curve (coordinates in internal feet). Default false." },
                         bounding_box = new { type = "boolean", description = "Model bounding box min/max (internal feet). Default false." },
                         materials = new { type = "boolean", description = "Material ids/names with area/volume (internal units). Default false." },
@@ -70,9 +78,9 @@ namespace RevitBridge.Tools
             JsonElement include = args.TryGetProperty("include", out var includeElement) && includeElement.ValueKind == JsonValueKind.Object
                 ? includeElement
                 : default;
-            bool withParameters = JsonArgs.GetBool(include, "parameters", true);
-            bool withTypeParameters = JsonArgs.GetBool(include, "type_parameters", false);
-            bool withAnyParameters = withParameters || withTypeParameters;
+            bool withParameters = JsonArgs.GetBool(include, "parameters", true);
+            bool withTypeParameters = JsonArgs.GetBool(include, "type_parameters", false);
+            bool withAnyParameters = withParameters || withTypeParameters;
             bool withLocation = JsonArgs.GetBool(include, "location", false);
             bool withBoundingBox = JsonArgs.GetBool(include, "bounding_box", false);
             bool withMaterials = JsonArgs.GetBool(include, "materials", false);
@@ -103,11 +111,11 @@ namespace RevitBridge.Tools
 
                 int parameterCount = 0;
                 int parameterTotal = 0;
-                if (withAnyParameters)
-                {
-                    var parameters = new List<Dictionary<string, object?>>();
-                    if (withParameters)
-                        parameterTotal += AppendParameters(doc, element, nameFilter, isType: false, parameters);
+                if (withAnyParameters)
+                {
+                    var parameters = new List<Dictionary<string, object?>>();
+                    if (withParameters)
+                        parameterTotal += AppendParameters(doc, element, nameFilter, isType: false, parameters);
                     if (withTypeParameters && elementType != null)
                         parameterTotal += AppendParameters(doc, elementType, nameFilter, isType: true, parameters);
                     dto["parameters"] = parameters;
@@ -124,7 +132,7 @@ namespace RevitBridge.Tools
                 elements.Add(dto);
                 // With a name filter active, "0 params" is ambiguous (none matched vs none
                 // exist): report matched-of-total so a localization miss is visible.
-                string paramSummary = !withAnyParameters ? string.Empty
+                string paramSummary = !withAnyParameters ? string.Empty
                     : nameFilter != null ? $", {parameterCount} of {parameterTotal} params matched parameter_names"
                     : $", {parameterCount} params";
                 compactParts.Add($"'{element.Name}' (id {id}, {element.Category?.Name ?? "no category"}{paramSummary})");
@@ -167,37 +175,25 @@ namespace RevitBridge.Tools
             return total;
         }
 
-        internal static IReadOnlyList<object> ProjectParameters(Document doc, Element element, IReadOnlyList<string> names, bool includeType)
-        {
-            var result = new List<object>();
-            void Project(Element source, bool isType)
-            {
-                foreach (string input in names.Distinct(StringComparer.OrdinalIgnoreCase))
-                {
-                    IEnumerable<Parameter> matches;
-                    if (input.StartsWith("guid:", StringComparison.OrdinalIgnoreCase))
-                    {
-                        if (!Guid.TryParse(input[5..], out var guid)) throw new ArgumentException($"Invalid shared parameter identity: {input}");
-                        var parameter = source.get_Parameter(guid);
-                        matches = parameter == null ? Array.Empty<Parameter>() : new[] { parameter };
-                    }
-                    else if (Enum.TryParse<BuiltInParameter>(input, true, out var builtIn) && Enum.IsDefined(builtIn) && builtIn != BuiltInParameter.INVALID)
-                    {
-                        var parameter = source.get_Parameter(builtIn);
-                        matches = parameter == null ? Array.Empty<Parameter>() : new[] { parameter };
-                    }
-                    else
-                        matches = source.Parameters.Cast<Parameter>().Where(p => string.Equals(p.Definition?.Name, input, StringComparison.OrdinalIgnoreCase));
-                    var values = matches.Select(p => DescribeParameter(doc, p, p.Definition?.Name ?? "", isType)).ToArray();
-                    result.Add(new { requested = input, isType, found = values.Length > 0, ambiguous = values.Length > 1, matches = values });
-                }
-            }
-            Project(element, false);
-            if (includeType && doc.GetElement(element.GetTypeId()) is { } type) Project(type, true);
-            return result;
-        }
-
-        internal static Dictionary<string, object?> DescribeParameter(Document doc, Parameter parameter, string name, bool isType)
+        internal static IReadOnlyList<object> ProjectParameters(Document doc, Element element, IReadOnlyList<string> names, bool includeType)
+        {
+            var result = new List<object>();
+            void Project(Element source, bool isType)
+            {
+                foreach (string input in names.Distinct(StringComparer.OrdinalIgnoreCase))
+                {
+                    // Shared policy: projections report every match and flag ambiguity instead of choosing.
+                    var matches = ParameterResolver.FindAll(source, ParameterReference.Parse(input));
+                    var values = matches.Select(p => DescribeParameter(doc, p, p.Definition?.Name ?? "", isType)).ToArray();
+                    result.Add(new { requested = input, isType, found = values.Length > 0, ambiguous = values.Length > 1, matches = values });
+                }
+            }
+            Project(element, false);
+            if (includeType && doc.GetElement(element.GetTypeId()) is { } type) Project(type, true);
+            return result;
+        }
+
+        internal static Dictionary<string, object?> DescribeParameter(Document doc, Parameter parameter, string name, bool isType)
         {
             bool hasValue = parameter.HasValue;
             var row = new Dictionary<string, object?>

package/src/Revit/Tools/GetElementRelationships.cs

@@ -1,76 +1,82 @@
-using System.Text.Json;
-using Autodesk.Revit.DB;
-
-namespace RevitBridge.Tools;
-
-internal sealed class GetElementRelationships : ITool
-{
-    public string Name => "get_element_relationships";
-    public string Label => "Get Element Relationships";
-    public string Tier => "advanced";
-    public string Description => "Inspect host-document element relationships: type, level, owning view, host, family parent/subcomponents, group or assembly membership, joined geometry and logical dependents. Dependents are not a complete deletion-impact prediction. Pagination applies independently to each relationship; links are not traversed.";
-    private static readonly string[] Kinds = { "type", "level", "owner_view", "host", "parent", "subcomponents", "group", "assembly", "members", "joined", "dependents" };
-    public object ParametersSchema => new
-    {
-        type = "object",
-        properties = new
-        {
-            element_id = new { type = "integer" },
-            relationships = new { type = "array", items = new { type = "string", @enum = Kinds } },
-            offset = new { type = "integer", minimum = 0 },
-            limit = new { type = "integer", minimum = 1, maximum = 200 },
-        },
-        required = new[] { "element_id" },
-    };
-
-    public object Execute(JsonElement args, ToolContext context)
-    {
-        var doc = context.Document ?? throw new NoActiveDocumentException();
-        var id = JsonArgs.GetLong(args, "element_id") ?? throw new ArgumentException("element_id is required.");
-        var element = doc.GetElement(new ElementId(id)) ?? throw new ArgumentException("element_id does not exist in the active document.");
-        var kinds = (IReadOnlyList<string>?)JsonArgs.GetStringArray(args, "relationships") ?? Kinds;
-        if (kinds.Any(kind => !Kinds.Contains(kind))) throw new ArgumentException("Unknown relationship kind.");
-        int offset = Math.Max(0, JsonArgs.GetInt(args, "offset", 0));
-        int limit = Math.Clamp(JsonArgs.GetInt(args, "limit", 100), 1, 200);
-        var result = new Dictionary<string, object?>();
-        foreach (var kind in kinds.Distinct())
-        {
-            IEnumerable<ElementId> ids = kind switch
-            {
-                "type" => One(element.GetTypeId()),
-                "level" => One(element.LevelId),
-                "owner_view" => One(element.OwnerViewId),
-                "host" => One((element as FamilyInstance)?.Host?.Id),
-                "parent" => One((element as FamilyInstance)?.SuperComponent?.Id),
-                "subcomponents" => element is FamilyInstance family ? family.GetSubComponentIds() : Array.Empty<ElementId>(),
-                "group" => One(element.GroupId),
-                "assembly" => One(element.AssemblyInstanceId),
-                "members" => element is Group group ? group.GetMemberIds()
-                    : element is AssemblyInstance assembly ? assembly.GetMemberIds() : Array.Empty<ElementId>(),
-                "joined" => Joined(doc, element),
-                "dependents" => element.GetDependentElements(null),
-                _ => Array.Empty<ElementId>(),
-            };
-            var all = ids.Where(x => x != ElementId.InvalidElementId).DistinctBy(x => x.Value).OrderBy(x => x.Value).ToList();
-            var rows = all.Skip(offset).Take(limit).Select(x =>
-            {
-                var related = doc.GetElement(x);
-                return new { id = x.Value, name = related?.Name, category = related?.Category?.Name, unique_id = related?.UniqueId };
-            }).ToArray();
-            result[kind] = new { total_count = all.Count, returned_count = rows.Length, offset,
-                has_more = offset + rows.Length < all.Count,
-                next_offset = offset + rows.Length < all.Count ? (int?)(offset + rows.Length) : null, elements = rows };
-        }
-        return new { document_id = DocumentGuard.GetIdentity(doc), element_id = id, relationships = result };
-    }
-
-    private static IEnumerable<ElementId> One(ElementId? id)
-        => id == null || id == ElementId.InvalidElementId ? Array.Empty<ElementId>() : new[] { id };
-
-    private static IEnumerable<ElementId> Joined(Document doc, Element element)
-    {
-        // JoinGeometryUtils rejects family documents; surface that restriction explicitly.
-        if (doc.IsFamilyDocument) throw new ArgumentException("joined relationships require a project document. Request other relationship kinds for families.");
-        return JoinGeometryUtils.GetJoinedElements(doc, element);
-    }
-}
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class GetElementRelationships : ITool
+{
+    public string Name => "get_element_relationships";
+    public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+    public IReadOnlyList<string> Keywords => new[] { "host", "hosted", "dependents", "nested", "group members", "joined", "relationship", "family hierarchy" };
+    public IReadOnlyList<ToolLimit> Limits => new[]
+    {
+        new ToolLimit("A complete prediction of deletion effects", "tool", "delete_elements with preview"),
+    };
+    public string Label => "Get Element Relationships";
+    public string Tier => "advanced";
+    public string Description => "Inspect host-document element relationships: type, level, owning view, host, family parent/subcomponents, group or assembly membership, joined geometry and logical dependents. Dependents are not a complete deletion-impact prediction. Pagination applies independently to each relationship; links are not traversed.";
+    private static readonly string[] Kinds = { "type", "level", "owner_view", "host", "parent", "subcomponents", "group", "assembly", "members", "joined", "dependents" };
+    public object ParametersSchema => new
+    {
+        type = "object",
+        properties = new
+        {
+            element_id = new { type = "integer" },
+            relationships = new { type = "array", items = new { type = "string", @enum = Kinds } },
+            offset = new { type = "integer", minimum = 0 },
+            limit = new { type = "integer", minimum = 1, maximum = 200 },
+        },
+        required = new[] { "element_id" },
+    };
+
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        var id = JsonArgs.GetLong(args, "element_id") ?? throw new ArgumentException("element_id is required.");
+        var element = doc.GetElement(new ElementId(id)) ?? throw new ArgumentException("element_id does not exist in the active document.");
+        var kinds = (IReadOnlyList<string>?)JsonArgs.GetStringArray(args, "relationships") ?? Kinds;
+        if (kinds.Any(kind => !Kinds.Contains(kind))) throw new ArgumentException("Unknown relationship kind.");
+        int offset = Math.Max(0, JsonArgs.GetInt(args, "offset", 0));
+        int limit = Math.Clamp(JsonArgs.GetInt(args, "limit", 100), 1, 200);
+        var result = new Dictionary<string, object?>();
+        foreach (var kind in kinds.Distinct())
+        {
+            IEnumerable<ElementId> ids = kind switch
+            {
+                "type" => One(element.GetTypeId()),
+                "level" => One(element.LevelId),
+                "owner_view" => One(element.OwnerViewId),
+                "host" => One((element as FamilyInstance)?.Host?.Id),
+                "parent" => One((element as FamilyInstance)?.SuperComponent?.Id),
+                "subcomponents" => element is FamilyInstance family ? family.GetSubComponentIds() : Array.Empty<ElementId>(),
+                "group" => One(element.GroupId),
+                "assembly" => One(element.AssemblyInstanceId),
+                "members" => element is Group group ? group.GetMemberIds()
+                    : element is AssemblyInstance assembly ? assembly.GetMemberIds() : Array.Empty<ElementId>(),
+                "joined" => Joined(doc, element),
+                "dependents" => element.GetDependentElements(null),
+                _ => Array.Empty<ElementId>(),
+            };
+            var all = ids.Where(x => x != ElementId.InvalidElementId).DistinctBy(x => x.Value).OrderBy(x => x.Value).ToList();
+            var rows = all.Skip(offset).Take(limit).Select(x =>
+            {
+                var related = doc.GetElement(x);
+                return new { id = x.Value, name = related?.Name, category = related?.Category?.Name, unique_id = related?.UniqueId };
+            }).ToArray();
+            result[kind] = new { total_count = all.Count, returned_count = rows.Length, offset,
+                has_more = offset + rows.Length < all.Count,
+                next_offset = offset + rows.Length < all.Count ? (int?)(offset + rows.Length) : null, elements = rows };
+        }
+        return new { document_id = DocumentGuard.GetIdentity(doc), element_id = id, relationships = result };
+    }
+
+    private static IEnumerable<ElementId> One(ElementId? id)
+        => id == null || id == ElementId.InvalidElementId ? Array.Empty<ElementId>() : new[] { id };
+
+    private static IEnumerable<ElementId> Joined(Document doc, Element element)
+    {
+        // JoinGeometryUtils rejects family documents; surface that restriction explicitly.
+        if (doc.IsFamilyDocument) throw new ArgumentException("joined relationships require a project document. Request other relationship kinds for families.");
+        return JoinGeometryUtils.GetJoinedElements(doc, element);
+    }
+}

package/src/Revit/Tools/GetElementTypes.cs

@@ -9,6 +9,14 @@ namespace RevitBridge.Tools
         private const int MaxLimit = 1000;
 
         public string Name => "get_element_types";
+        public IReadOnlyList<string> DocumentKinds => DocumentKind.Both;
+        public IReadOnlyList<string> Keywords => new[] { "types", "family types", "family symbols", "unused types", "loaded families", "purge candidates" };
+        public IReadOnlyList<ToolLimit> Limits => new[]
+        {
+            new ToolLimit("Creating or duplicating types", "api", "ElementType.Duplicate"),
+            new ToolLimit("Loading families", "api", "Document.LoadFamily"),
+            new ToolLimit("The types of the family being edited in a family document", "api", DocumentKind.FamilyApi),
+        };
         public string Label => "Get Element Types";
         public string Description => "List element types / family symbols (wall types, door types, ...) for a category or class: id, name, familyName, category, isFamilySymbol, optional placed-instance count per type (answers 'used vs merely loaded'). Use the ids with get_elements type_id or for type assignment.";