pi-revit 0.3.0 → 0.4.0

package/src/Revit/Tools/ElementQueryScope.cs

@@ -0,0 +1,27 @@
+using System.Text.Json;
+using System.Text.Json.Nodes;
+
+namespace RevitBridge.Tools;
+
+internal static class ElementQueryScope
+{
+    public static JsonObject Schema()
+    {
+        var schema = JsonSerializer.SerializeToNode(new GetElements().ParametersSchema)!.AsObject();
+        foreach (string key in new[] { "count_only", "fields", "offset", "limit", "parameter_names", "include_type_parameters" })
+            schema["properties"]!.AsObject().Remove(key);
+        schema["description"] = "Filter the whole matching scope. Query paging and projections are not supported here.";
+        schema["additionalProperties"] = false;
+        return schema;
+    }
+
+    public static JsonObject Parse(JsonElement args)
+    {
+        var query = args.TryGetProperty("query", out var input) ? JsonNode.Parse(input.GetRawText()) as JsonObject : new JsonObject();
+        if (query == null) throw new ArgumentException("query must be an object.");
+        var allowed = Schema()["properties"]!.AsObject();
+        foreach (var property in query)
+            if (!allowed.ContainsKey(property.Key)) throw new ArgumentException($"query does not support '{property.Key}'. It always uses the whole matching scope.");
+        return query;
+    }
+}

package/src/Revit/Tools/ExecuteCsharp.cs

@@ -20,11 +20,12 @@ namespace RevitBridge.Tools
     /// </summary>
     public sealed class ScriptGlobals
     {
-        internal ScriptGlobals(Document document, UIDocument uiDocument, UIApplication uiApplication, Action<object?> dump)
+        internal ScriptGlobals(Document document, UIDocument uiDocument, UIApplication uiApplication, JsonElement inputValues, Action<object?> dump)
         {
             doc = document;
             uidoc = uiDocument;
-            uiapp = uiApplication;
+            uiapp = uiApplication;
+            inputs = inputValues;
             Dump = dump;
         }
 
@@ -35,7 +36,10 @@ namespace RevitBridge.Tools
         public UIDocument uidoc { get; }
 
         /// <summary>The Revit UI application.</summary>
-        public UIApplication uiapp { get; }
+        public UIApplication uiapp { get; }
+
+        /// <summary>Structured inputs supplied separately from the script source.</summary>
+        public JsonElement inputs { get; }
 
         /// <summary>Records a value into the result's dumps[] (safely projected at call time).</summary>
         public Action<object?> Dump { get; }
@@ -59,19 +63,21 @@ namespace RevitBridge.Tools
 
         public string Name => "execute_csharp";
         public string Label => "Execute C#";
-        public string Description => "Compile and run a C# script on the Revit API thread against the open model — the escape hatch for anything without a dedicated tool: element creation, deletion, geometry edits (move/copy/rotate), views, sheets, schedules, tagging, families, links, worksets. Globals: doc (Document), uidoc (UIDocument), uiapp (UIApplication), and Dump(value) to record intermediate values into the result's dumps[]. Default imports: System, System.Linq, System.Collections.Generic, Autodesk.Revit.DB, Autodesk.Revit.UI — add using directives at the top for sub-namespaces (e.g. using Autodesk.Revit.DB.Architecture;). The entire run is wrapped in ONE transaction named 'execute_csharp': committed on success; on failure rollback is attempted and its confirmed status is reported (do not open your own Transaction; sub-transactions are fine). The script's final expression or return statement becomes returnValue; return primitives, strings, or anonymous objects/lists — Revit API values are projected to safe shapes (Element -> {id,name,category,typeName,levelId}, ElementId -> number, XYZ -> {x,y,z}, Parameter -> {name,value,displayValue}; other API objects become strings) with depth and item caps, so never rely on raw API objects round-tripping. Lengths are in internal units (decimal feet) — convert with UnitUtils. Prefer collector-level filtering (FilteredElementCollector .OfCategory/.OfClass/.WhereElementIsNotElementType) and bounded loops: the call budget is 120s and Revit cannot be interrupted mid-script. Scripts must be fully synchronous — await/async is rejected at compile time, and blocking on tasks (Task.Result/.Wait()) can freeze Revit. Modal dialogs raised while running are auto-dismissed and reported in suppressedDialogs — unrecognized dialogs are answered dismissively (Cancel/Close/No) rather than confirmed, so an operation that raises a confirmation prompt may be cancelled; check suppressedDialogs when a result looks incomplete. Verify unfamiliar signatures with search_api_docs first.";
-        public bool Write => true;
+        public string Description => "Compile and run a C# script on the Revit API thread against the open model — the escape hatch for anything without a dedicated tool: element creation, deletion, geometry edits (move/copy/rotate), views, sheets, schedules, tagging, families, links, worksets. Globals: doc (Document), uidoc (UIDocument), uiapp (UIApplication), inputs (System.Text.Json.JsonElement, defaults to an empty object), and Dump(value) to record intermediate values into the result's dumps[]. Default imports: System, System.Linq, System.Collections.Generic, Autodesk.Revit.DB, Autodesk.Revit.UI — add using directives at the top for sub-namespaces (e.g. using Autodesk.Revit.DB.Architecture;). The entire run is wrapped in ONE transaction named 'execute_csharp': committed on success; on failure rollback is attempted and its confirmed status is reported (do not open your own Transaction; sub-transactions are fine). The script's final expression or return statement becomes returnValue; return primitives, strings, or anonymous objects/lists — Revit API values are projected to safe shapes (Element -> {id,name,category,typeName,levelId}, ElementId -> number, XYZ -> {x,y,z}, Parameter -> {name,value,displayValue}; other API objects become strings) with depth and item caps, so never rely on raw API objects round-tripping. Lengths are in internal units (decimal feet) — convert with UnitUtils. Prefer collector-level filtering (FilteredElementCollector .OfCategory/.OfClass/.WhereElementIsNotElementType) and bounded loops: the call budget is 120s and Revit cannot be interrupted mid-script. Scripts must be fully synchronous — await/async is rejected at compile time, and blocking on tasks (Task.Result/.Wait()) can freeze Revit. Modal dialogs raised while running are auto-dismissed and reported in suppressedDialogs — unrecognized dialogs are answered dismissively (Cancel/Close/No) rather than confirmed, so an operation that raises a confirmation prompt may be cancelled; check suppressedDialogs when a result looks incomplete. Verify unfamiliar signatures with search_api_docs first.";
+        public bool Write => true;
+        public IReadOnlyList<string> Effects => new[] { "model", "ui", "files", "external" };
 
         public object ParametersSchema => new
         {
             type = "object",
             properties = new
             {
-                code = new
+                code = new
                 {
                     type = "string",
-                    description = "C# script body (top-level statements; using directives allowed at the top). Globals doc/uidoc/uiapp and Dump(value) are in scope. The final expression or a return statement is the result.",
-                },
+                    description = "C# script body (top-level statements; using directives allowed at the top). Globals doc/uidoc/uiapp/inputs and Dump(value) are in scope. The final expression or a return statement is the result.",
+                },
+                inputs = new { type = "object", description = "Optional structured JSON inputs, available as the inputs JsonElement global. Default empty object. Values are never interpolated into source code." },
                 expected_document = new
                 {
                     type = "string",
@@ -96,8 +102,11 @@ namespace RevitBridge.Tools
             DocumentGuard.CheckExpectedDocument(args, doc);
 
             string code = JsonArgs.GetString(args, "code") ?? string.Empty;
-            if (string.IsNullOrWhiteSpace(code))
-                throw new ArgumentException("code must be a non-empty C# script.");
+            if (string.IsNullOrWhiteSpace(code))
+                throw new ArgumentException("code must be a non-empty C# script.");
+            var inputValues = args.TryGetProperty("inputs", out var suppliedInputs) ? suppliedInputs.Clone() : JsonSerializer.SerializeToElement(new { });
+            if (inputValues.ValueKind != JsonValueKind.Object) throw new ArgumentException("inputs must be a JSON object.");
+            if (inputValues.GetRawText().Length > 100000) throw new ArgumentException("inputs must not exceed 100,000 JSON characters.");
 
             var stopwatch = Stopwatch.StartNew();
 
@@ -109,7 +118,7 @@ namespace RevitBridge.Tools
             RejectAsyncCode(script.GetCompilation());
 
             var dumps = new List<object?>();
-            var globals = new ScriptGlobals(doc, uidoc, uiapp, value =>
+            var globals = new ScriptGlobals(doc, uidoc, uiapp, inputValues, value =>
             {
                 if (dumps.Count < MaxDumps)
                     dumps.Add(Project(value, 0));
@@ -194,7 +203,8 @@ namespace RevitBridge.Tools
                 Assembly.Load("netstandard"),
                 typeof(Enumerable).Assembly,                                // System.Linq
                 typeof(Regex).Assembly,                                     // System.Text.RegularExpressions
-                typeof(Console).Assembly,                                   // System.Console
+                typeof(Console).Assembly,                                   // System.Console
+                typeof(JsonElement).Assembly,                               // System.Text.Json
                 typeof(Document).Assembly,                                  // RevitAPI
                 typeof(UIApplication).Assembly)                             // RevitAPIUI
             .WithImports("System", "System.Linq", "System.Collections.Generic", "Autodesk.Revit.DB", "Autodesk.Revit.UI")
@@ -209,7 +219,7 @@ namespace RevitBridge.Tools
             });
             string more = errors.Count > MaxReportedErrors ? $"\n  … +{errors.Count - MaxReportedErrors} more error(s)" : string.Empty;
             return $"C# compilation failed with {errors.Count} error(s):\n{string.Join("\n", lines)}{more}\n"
-                + "Globals: doc, uidoc, uiapp, Dump(value). Default imports: System, System.Linq, System.Collections.Generic, "
+                + "Globals: doc, uidoc, uiapp, inputs (JsonElement), Dump(value). Default imports: System, System.Linq, System.Collections.Generic, "
                 + "Autodesk.Revit.DB, Autodesk.Revit.UI — add using directives for other namespaces.";
         }
 

package/src/Revit/Tools/ExportDocuments.cs

@@ -22,7 +22,8 @@ namespace RevitBridge.Tools
         public string Name => "export_documents";
         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 bool Write => true;
+        public IReadOnlyList<string> Effects => new[] { "model", "files" };
         public string Tier => "advanced";
 
         public object ParametersSchema => new

package/src/Revit/Tools/GetElementDetails.cs

@@ -10,7 +10,7 @@ namespace RevitBridge.Tools
 
         public string Name => "get_element_details";
         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. The single home for reading parameter values — get_elements only returns identity fields.";
+        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.";
 
         public object ParametersSchema => new
         {
@@ -167,7 +167,37 @@ namespace RevitBridge.Tools
             return total;
         }
 
-        private 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))
+                {
+                    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)
         {
             bool hasValue = parameter.HasValue;
             var row = new Dictionary<string, object?>

package/src/Revit/Tools/GetElementRelationships.cs

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

package/src/Revit/Tools/GetElements.cs

@@ -21,7 +21,7 @@ namespace RevitBridge.Tools
 
         public string Name => "get_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 only (id, name, category, typeName, levelId) — read parameter values with get_element_details. 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,12 +72,18 @@ 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." },
+                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",
                     items = new { type = "string", @enum = new[] { "id", "name", "category", "typeName", "levelId" } },
-                    description = "Identity fields per row; default all five. id is always included. Parameter values live in get_element_details.",
+                    description = "Identity fields per row; default all five. id is always included. Use parameter_names for optional values alongside these fields.",
                 },
                 offset = new { type = "integer", description = "Pagination offset. Default 0." },
                 limit = new { type = "integer", description = "Max rows to return (1-1000). Default 200." },
@@ -89,7 +95,7 @@ namespace RevitBridge.Tools
         public IReadOnlyList<string>? PromptGuidelines => new[]
         {
             "Use get_elements to list or count elements of any category or class (walls, doors, rooms, sheets, views, ...); use the returned ids with the other Revit tools.",
-            "get_elements returns identity fields only; read parameter values with get_element_details.",
+            "get_elements can project up to 20 parameter_names per row; use get_element_details for full element inspection.",
         };
 
         public object? Execute(JsonElement args, ToolContext context)
@@ -103,7 +109,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 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);
@@ -158,8 +167,13 @@ namespace RevitBridge.Tools
             {
                 if (postPredicate != null && !postPredicate(element))
                     continue;
-                if (rows != null && total >= offset && rows.Count < limit)
-                    rows.Add(ElementIdentity.Build(doc, element, fields));
+                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++;
             }
 

package/src/Revit/Tools/GetLinkedElements.cs

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

package/src/Revit/Tools/GetLinkedModels.cs

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

package/src/Revit/Tools/GetModelCoordinates.cs

@@ -0,0 +1,49 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class GetModelCoordinates : ITool
+{
+    public string Name => "get_model_coordinates";
+    public string Label => "Get Model Coordinates";
+    public string Tier => "advanced";
+    public string Description => "Read project/survey base points, active project location and site coordinates. Optionally report shared coordinates for up to 100 points expressed along document internal axes. Required unit applies to input points and every returned length; angles and latitude/longitude are degrees. The active location's Revit GetProjectPosition defines the shared mapping. List project locations with paging. Does not infer a GIS coordinate reference system or modify/acquire coordinates.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            unit = ModelEditInputs.LengthUnitSchema,
+            points = new { type = "array", maxItems = 100, items = ModelEditInputs.VectorSchema("Point along document internal axes, in unit.") },
+            offset = new { type = "integer", minimum = 0 }, limit = new { type = "integer", minimum = 1, maximum = 100 },
+        }, required = new[] { "unit" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        if (doc.IsFamilyDocument) throw new ArgumentException("Project coordinates require a project document.");
+        double scale = ModelEditInputs.LengthScale(args);
+        var active = doc.ActiveProjectLocation;
+        object Position(ProjectPosition position) => new { east_west = position.EastWest / scale, north_south = position.NorthSouth / scale, elevation = position.Elevation / scale, angle_degrees = position.Angle * 180 / Math.PI };
+        object? Base(BasePoint? point) => point == null ? null : new { id = point.Id.Value, internal_position = SpatialBounds.Coordinates(point.Position, scale), shared_position = SpatialBounds.Coordinates(point.SharedPosition, scale) };
+        var points = new List<object>();
+        if (args.TryGetProperty("points", out var values))
+        {
+            if (values.ValueKind != JsonValueKind.Array || values.GetArrayLength() > 100) throw new ArgumentException("points must be an array of at most 100 XYZ points.");
+            foreach (var value in values.EnumerateArray())
+            {
+                var wrapper = JsonSerializer.SerializeToElement(new { point = value });
+                var point = ModelEditInputs.Vector(wrapper, "point").Multiply(scale);
+                points.Add(new { internal_position = SpatialBounds.Coordinates(point, scale), shared_position = Position(active.GetProjectPosition(point)) });
+            }
+        }
+        var locations = doc.ProjectLocations.Cast<ProjectLocation>().OrderBy(x => x.Id.Value).ToList();
+        int offset = Math.Max(0, JsonArgs.GetInt(args, "offset", 0)), limit = Math.Clamp(JsonArgs.GetInt(args, "limit", 50), 1, 100);
+        var page = locations.Skip(offset).Take(limit).Select(x => new { id = x.Id.Value, name = x.Name, active = x.Id == active.Id, internal_origin_in_shared_coordinates = Position(x.GetProjectPosition(XYZ.Zero)) }).ToArray();
+        var site = doc.SiteLocation;
+        return new { unit = JsonArgs.GetString(args, "unit"), angle_unit = "degrees", point_input_coordinates = "document_internal", active_project_location = new { id = active.Id.Value, name = active.Name },
+            project_base_point = Base(BasePoint.GetProjectBasePoint(doc)), survey_point = Base(BasePoint.GetSurveyPoint(doc)),
+            site = new { name = site.Name, latitude_degrees = site.Latitude * 180 / Math.PI, longitude_degrees = site.Longitude * 180 / Math.PI, time_zone = site.TimeZone },
+            total_locations = locations.Count, offset, next_offset = offset + page.Length < locations.Count ? (int?)(offset + page.Length) : null, locations = page, points };
+    }
+}

package/src/Revit/Tools/GetScheduleFields.cs

@@ -0,0 +1,37 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class GetScheduleFields : ITool
+{
+    public string Name => "get_schedule_fields";
+    public string Label => "Get Schedule Fields";
+    public string Tier => "advanced";
+    public string Description => "List fields eligible to be added to one existing schedule, with paging and localized-name filtering. A field is identified by the pair parameter_id + field_type; negative built-in parameter IDs are valid. These identities differ from schedule-local field_id values returned by get_schedules. Existing fields are marked included. Count may appear in the returned fields; manage_schedules accepts its discovered pair or field_type Count without a parameter_id. Calculated/combined fields are not exposed here.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            schedule_id = new { type = "integer", minimum = 1 }, name_filter = new { type = "string" },
+            offset = new { type = "integer", minimum = 0 }, limit = new { type = "integer", minimum = 1, maximum = 200 },
+        }, required = new[] { "schedule_id" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        var schedule = doc.GetElement(new ElementId(JsonArgs.GetLong(args, "schedule_id") ?? 0)) as ViewSchedule ?? throw new ArgumentException("schedule_id is not a schedule.");
+        if (schedule.IsTemplate || schedule.IsTitleblockRevisionSchedule) throw new ArgumentException("Use a regular schedule, not a template or titleblock revision schedule.");
+        int offset = JsonArgs.GetInt(args, "offset", 0), limit = JsonArgs.GetInt(args, "limit", 100);
+        if (offset < 0 || limit is < 1 or > 200) throw new ArgumentException("Invalid paging range.");
+        string needle = JsonArgs.GetString(args, "name_filter") ?? "";
+        var definition = schedule.Definition;
+        var included = definition.GetFieldOrder().Select(id => definition.GetField(id)).Select(f => (f.ParameterId.Value, f.FieldType)).ToHashSet();
+        var fields = definition.GetSchedulableFields().Select(f => new
+        {
+            parameter_id = f.ParameterId.Value, field_type = f.FieldType.ToString(), name = f.GetName(doc), included = included.Contains((f.ParameterId.Value, f.FieldType)),
+        }).Where(f => f.name.Contains(needle, StringComparison.OrdinalIgnoreCase)).OrderBy(f => f.parameter_id).ThenBy(f => f.field_type, StringComparer.Ordinal).ToArray();
+        var page = fields.Skip(offset).Take(limit).ToArray();
+        return new { schedule_id = schedule.Id.Value, total_count = fields.Length, offset, returned_count = page.Length, next_offset = offset + page.Length < fields.Length ? (int?)(offset + page.Length) : null, fields = page };
+    }
+}