@rui.branco/revit-mcp 1.0.0

package/lib/tools/model.js

@@ -0,0 +1,285 @@
+// Site, hardscape and family placement: the tools that put modelled elements in
+// the document rather than drawing-side ones.
+//
+// Like every other write, the Revit side wraps a whole call in one transaction
+// group, so a batch of 200 points is exactly one Ctrl+Z for the user.
+//
+// All lengths and coordinates are Revit internal units: decimal feet.
+
+import { z } from "zod";
+
+const point3 = z.object({
+  x: z.number(),
+  y: z.number(),
+  z: z.number().optional().describe("Elevation in feet; defaults to 0"),
+});
+
+// z is the surface elevation at that point for a toposolid, so it is not optional there.
+const surveyPoint = z.object({
+  x: z.number(),
+  y: z.number(),
+  z: z.number().describe("Surface elevation at this point, in feet"),
+});
+
+const point2 = z.object({ x: z.number(), y: z.number() });
+
+export function registerModelTools(server, bridge) {
+  server.tool(
+    "revit_create_toposolid",
+    "Create the site surface from a cloud of survey points. Uses a Revit 2024+ Toposolid when the document has a toposolid type, and falls back to the legacy TopographySurface when it has none — the response says which in 'type'. Points are x/y/z in feet (Revit internal units) and z is the surface elevation at that point, so it matters here. One call is one undo step.",
+    {
+      points: z
+        .array(surveyPoint)
+        .min(3)
+        .describe("Survey points defining the top face, at least 3, in feet"),
+      type_name: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Toposolid type name. Omit it to use the first one in the document."),
+      level: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Level the toposolid is hosted on. Omit it to use the lowest level in the document."),
+    },
+    async ({ points, type_name, level }) => {
+      try {
+        const result = await bridge.call("/toposolid/create", {
+          points,
+          typeName: type_name,
+          level,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_flatten_toposolid",
+    "Flatten a region of the site surface to one elevation, so paving can sit on graded terrain instead of fighting it — this is the fix for Revit's 'Highlighted toposolid and floor overlap' warning. 'points' is a ring in plan and 'elevation' is what to level it to, both in feet (Revit internal units). The ring is added to the surface at that elevation, creased so the flat region ends at its boundary, and every existing surface point inside it is moved to match. The response reports 'residual' — the largest distance any point in the region is still off the target — so check that rather than assuming it worked. Only a Revit 2024+ Toposolid can be flattened; a legacy TopographySurface cannot. One call is one undo step.",
+    {
+      points: z
+        .array(point2)
+        .min(3)
+        .describe("Region boundary in plan, in feet. Closed automatically; at least 3 points."),
+      elevation: z.number().describe("Elevation to flatten the region to, in feet"),
+      toposolid_id: z
+        .number()
+        .int()
+        .optional()
+        .describe("Id of the toposolid to flatten. Only needed when the document has more than one."),
+    },
+    async ({ points, elevation, toposolid_id }) => {
+      try {
+        const result = await bridge.call("/toposolid/flatten", {
+          points,
+          elevation,
+          toposolidId: toposolid_id,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_create_floor",
+    "Create a floor from a closed boundary: paving, a pool deck, a terrace, or an actual building floor. The boundary is a ring of x/y points in feet (Revit internal units) taken at the level's elevation, and it is closed automatically when the last point is not the first. 'offset' lifts the floor off its level (Revit's 'Height Offset From Level'), which is how paving clears a graded toposolid instead of interpenetrating it — the other half of that fix is revit_flatten_toposolid. One call is one undo step.",
+    {
+      level: z.string().min(1).describe("Level name the floor is hosted on"),
+      boundary: z
+        .array(point2)
+        .min(3)
+        .describe("Boundary ring in plan, in feet. Closed automatically; at least 3 points."),
+      type_name: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Floor type name, e.g. 'Generic - 300mm'. Omit it to use the document default."),
+      structural: z
+        .boolean()
+        .optional()
+        .describe("True for a structural floor, false (the default) for architectural"),
+      offset: z
+        .number()
+        .optional()
+        .describe(
+          "Height offset from the level in feet, positive up. Defaults to 0. Written to the floor's 'Height Offset From Level' parameter and read back into the response.",
+        ),
+    },
+    async ({ level, boundary, type_name, structural, offset }) => {
+      try {
+        const result = await bridge.call("/floors/create", {
+          level,
+          boundary,
+          typeName: type_name,
+          structural,
+          offset,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_load_families",
+    "Load .rfa family files into the project — real trees, benches, bollards, light fittings, doors and windows instead of DirectShape primitives. Autodesk's library is an optional download that lives OUTSIDE the project, under C:\\ProgramData\\Autodesk\\RVT <year>\\Libraries\\<language>\\ (Planting\\, Site\\Accessories\\, Lighting\\Architectural\\External\\, Furniture\\, Doors\\, Windows\\), so nothing in it exists to revit_list_family_symbols or revit_place_families until it is loaded here first. A library one Revit release behind loads fine — Revit upgrades the family on the way in, and anything it warned about comes back in 'warnings'. Every file comes back with the family name and its type ids, so you can place immediately without a second lookup. A family already in the project is reloaded rather than refused, keeping the parameter values the project has set. Read 'loaded' and 'alreadyLoaded' together: loaded false with alreadyLoaded true is not a failure, it means Revit found the project's copy identical to the file and did nothing — the familyName and symbols on that row are still the ones you want. Nothing aborts the batch: a missing file is FILE_NOT_FOUND on its own row and the rest still load. One call is one undo step.",
+    {
+      paths: z
+        .array(z.string().min(1))
+        .min(1)
+        .optional()
+        .describe("Full paths of .rfa files to load. Pass the whole batch in one call."),
+      path: z.string().min(1).optional().describe("A single .rfa path, as a shorthand for paths"),
+    },
+    async ({ paths, path }) => {
+      try {
+        if (!paths && !path) {
+          return {
+            content: [
+              { type: "text", text: "Error: pass 'paths' (an array of .rfa files) or 'path' (one)." },
+            ],
+          };
+        }
+        const result = await bridge.call("/families/load", paths ? { paths } : { path });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_list_family_symbols",
+    "List the family types loaded in the document: id, family name, type name and category. This is how you discover what revit_place_families can actually place. Filter by 'category', by 'family_name', or both — 'family_name' matches the family, so right after revit_load_families you can ask for exactly the file you just loaded. An empty list means no family content is loaded: load some with revit_load_families, and only fall back to revit_create_directshape or revit_place_planting if the library is genuinely not installed.",
+    {
+      category: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Category name to filter by, e.g. 'Planting' or 'OST_LightingFixtures'"),
+      family_name: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+          "Family name to filter by, e.g. 'M_RPC Tree - Deciduous'. This is the family, not the type — it returns every type in that family.",
+        ),
+    },
+    async ({ category, family_name }) => {
+      try {
+        const result = await bridge.call("/families/symbols", {
+          category,
+          familyName: family_name,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_place_families",
+    "Place one family instance per point — trees, shrubs, light fittings, furniture. Get symbol_id from revit_list_family_symbols (and put the family there first with revit_load_families). The symbol is activated for you if it has never been used. Points are x/y/z in feet (Revit internal units) and z is an ABSOLUTE model elevation, the same as everywhere else in this MCP — the bridge converts it to the level offset Revit's placement API actually wants, so a tree asked for at z=0 stands at z=0 whatever level it is on. 'level' is optional and defaults to the lowest level, which is where site content belongs; 'z' is an extra offset added to every point, for lifting a whole batch onto a terrace. Each placed point reports 'placedZ' read back off the instance, so you can check where things actually landed rather than trusting it. rotation is radians about the vertical axis. Pass every point in one call: the whole batch is one undo step, and a point Revit refuses comes back under 'failed' while the rest are still placed.",
+    {
+      symbol_id: z
+        .number()
+        .int()
+        .describe("Family type id from revit_list_family_symbols"),
+      level: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Level name the instances are associated with. Omit it for the lowest level."),
+      points: z
+        .array(point3)
+        .min(1)
+        .describe(
+          "Insertion points in feet, one instance per point, z an absolute model elevation. All in this one call.",
+        ),
+      z: z
+        .number()
+        .optional()
+        .describe("Extra elevation in feet added to every point's own z. Defaults to 0."),
+      rotation: z
+        .number()
+        .optional()
+        .describe(
+          "Rotation in radians about the vertical axis through each point, counter-clockwise in plan. Radians is Revit's internal angle unit, as feet is its internal length unit.",
+        ),
+    },
+    async ({ symbol_id, level, points, z: zOffset, rotation }) => {
+      try {
+        const result = await bridge.call("/families/place", {
+          symbolId: symbol_id,
+          level,
+          points,
+          z: zOffset,
+          rotation,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_place_openings",
+    "Place doors and windows IN walls — the tool for family instances that have to cut their host, which is why it is not revit_place_families with a flag. A door or window placed unhosted stands in front of an uncut wall: nearly right in plan, wrong in every 3D view, and the most common way a model of a house stays a sealed box. Get symbol_id from revit_list_family_symbols after revit_load_families; Autodesk's library keeps them under Doors\\ and Windows\\ (and Doors\\Residential\\ for the exterior ones). The symbol is activated for you if it has never been used. host_wall_id is OPTIONAL and leaving it out is the normal case: for each point the bridge projects onto every wall's location line and hosts in the nearest within 3 feet, then reports the wall each instance actually landed in — read back off the instance's host, not echoed, so a symbol that is not wall-hosted shows up as a null hostWallId rather than being assumed to have worked. A point with no wall near it comes back under 'failed' with NO_HOST_WALL and the rest of the batch still lands. Points are x/y/z in feet (Revit internal units) along the wall; z is the absolute model elevation of the insertion point. sill_height is feet above the level: omit it and a Windows-category symbol gets 3 feet (a window on the floor is not a window) while anything else keeps Revit's own. The row reports sillHeight read back and sillHeightOn — 'instance' normally, 'type' when the family keeps its sill on the type, and writing the type's moves every other instance of that type. Pass every opening in one call: the whole batch is one undo step.",
+    {
+      symbol_id: z
+        .number()
+        .int()
+        .describe("Door or window family type id from revit_list_family_symbols"),
+      points: z
+        .array(point3)
+        .min(1)
+        .describe(
+          "Insertion points in feet, one opening per point, z an absolute model elevation. All in this one call.",
+        ),
+      host_wall_id: z
+        .number()
+        .int()
+        .optional()
+        .describe(
+          "Wall to host every point in. Omit it to let the bridge host each point in the nearest wall within 3 feet and report which one it picked.",
+        ),
+      level: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Level name the openings are associated with. Omit it for the lowest level."),
+      sill_height: z
+        .number()
+        .optional()
+        .describe(
+          "Height of the sill above the level, in feet. Omit it for 3 feet on a window and Revit's own on anything else.",
+        ),
+    },
+    async ({ symbol_id, points, host_wall_id, level, sill_height }) => {
+      try {
+        // The tool arguments stay snake_case like every other tool's; the bridge
+        // reads symbolId / hostWallId / sillHeight — map them here rather than on
+        // the C# side.
+        const result = await bridge.call("/openings/place", {
+          symbolId: symbol_id,
+          points,
+          hostWallId: host_wall_id,
+          level,
+          sillHeight: sill_height,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+}

package/lib/tools/parameters.js

@@ -0,0 +1,140 @@
+// Project parameters: making one, and writing a different value per element.
+//
+// A project parameter in Revit is a shared parameter definition plus a binding
+// to categories. The definition lives in a text file outside the model, which
+// is a user-wide Revit setting — the bridge borrows it for the length of the
+// call and puts the original back, so creating a parameter never leaves the
+// user's Revit pointing somewhere new.
+//
+// revit_set_parameters (in write.js) is the other half of this and a different
+// job: it writes ONE name and ONE value across a list of ids, all or nothing.
+// The tool here writes a DIFFERENT value per sheet, which is what stamping a
+// phase across 56 sheets is.
+
+import { z } from "zod";
+
+export function registerParameterTools(server, bridge) {
+  server.tool(
+    "revit_create_project_parameter",
+    "Create a project parameter and bind it to one or more categories — the way to add a field Revit does not have, such as a Phase on sheets that the Project Browser can group by. Defaults to a Text instance parameter under Identity Data. Pass 'category' for one category or 'categories' for several; both name categories as Revit shows them ('Sheets') or as BuiltInCategory names ('OST_Sheets'). A parameter of that name already bound in this document is NOT an error: nothing is created, 'created' is false and 'alreadyExisted' is true, and the categories reported are the ones it is really bound to — so re-running the same call is safe. One call is one undo step. Write the values afterwards with revit_set_sheet_parameters (per sheet) or revit_set_parameters (one value across many elements).",
+    {
+      name: z.string().min(1).describe("Parameter name as it will appear in Revit, e.g. 'Phase'"),
+      category: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Single category to bind to, e.g. 'Sheets' or 'OST_Sheets'. Use this or categories, not both."),
+      categories: z
+        .array(z.string().min(1))
+        .min(1)
+        .optional()
+        .describe("Categories to bind to. Use this or category, not both."),
+      type: z
+        .enum([
+          "Text",
+          "MultilineText",
+          "Url",
+          "Integer",
+          "Number",
+          "YesNo",
+          "Length",
+          "Area",
+          "Volume",
+          "Angle",
+        ])
+        .optional()
+        .describe("Parameter data type. Defaults to Text. Length, Area, Volume and Angle are in Revit internal units (feet, square feet, cubic feet, radians)."),
+      group: z
+        .enum([
+          "IdentityData",
+          "Text",
+          "Data",
+          "General",
+          "Graphics",
+          "Constraints",
+          "Geometry",
+          "Phasing",
+          "Title",
+        ])
+        .optional()
+        .describe("Group the parameter appears under in the Properties palette. Defaults to IdentityData."),
+      instance: z
+        .boolean()
+        .optional()
+        .describe("True (the default) binds it per element; false binds it to the type, so every element of that type shares one value."),
+    },
+    async ({ name, category, categories, type, group, instance }) => {
+      // Checked here rather than in the schema: a raw shape cannot express
+      // "one of these two", and a call with neither must not reach Revit.
+      if (category === undefined && categories === undefined) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Error: pass either category (one) or categories (several).",
+            },
+          ],
+        };
+      }
+      if (category !== undefined && categories !== undefined) {
+        return {
+          content: [
+            { type: "text", text: "Error: pass either category or categories, not both." },
+          ],
+        };
+      }
+
+      try {
+        const result = await bridge.call("/parameters/create-project", {
+          name,
+          category,
+          categories,
+          type,
+          group,
+          instance,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_set_sheet_parameters",
+    "Write a parameter value per sheet — a different value on each, which is what stamping a phase or a discipline across a set of sheets is. Pass every sheet in one call: the whole batch is one undo step, and a sheet whose parameter is missing or read-only comes back under 'failed' with its code while the rest are still written. Instance parameters only: writing to the type would change every other sheet using it. Create the parameter first with revit_create_project_parameter bound to Sheets — a name no sheet carries comes back as PARAMETER_NOT_FOUND. Use revit_set_parameters instead when one value goes on many elements.",
+    {
+      values: z
+        .array(
+          z.object({
+            sheet_id: z.number().int().describe("Sheet id from revit_list_sheets"),
+            name: z
+              .string()
+              .min(1)
+              .describe("Parameter name as it appears in Revit, e.g. 'Phase'"),
+            value: z
+              .union([z.string(), z.number(), z.boolean()])
+              .describe("Value for this sheet. Numbers are in Revit internal units; booleans map to Yes/No parameters."),
+          }),
+        )
+        .min(1)
+        .describe("Sheet/name/value triples, all in this one call"),
+    },
+    async ({ values }) => {
+      try {
+        // The tool arguments stay snake_case like every other tool's; the bridge
+        // reads sheetId — map it here rather than on the C# side.
+        const result = await bridge.call("/sheets/set-parameter", {
+          values: values.map((entry) => ({
+            sheetId: entry.sheet_id,
+            name: entry.name,
+            value: entry.value,
+          })),
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }] };
+      }
+    },
+  );
+}

package/lib/tools/quality.js

@@ -0,0 +1,200 @@
+// Quality assurance: the tools that measure what is in the model rather than
+// add to it, plus the one edit safe enough to sit beside them.
+//
+// Every other read here is deliberately compact — id, name, category, type —
+// and compact cannot answer "is this tree standing in the pool", "is that chair
+// buried under the slab", "what grades is the paving sitting on". That needs
+// measured geometry, so this is the one place that reports it at length, and it
+// still bounds what comes back.
+//
+// All coordinates are absolute Revit model coordinates in decimal feet — the
+// document's internal origin, the same frame locations and bounding boxes are
+// reported in, never relative to a level or a view. The responses say so in
+// `coordinateSystem` rather than leaving it to be assumed.
+//
+// Every catch here answers with `isError: true`. A refusal these tools exist to
+// make — a pinned element, CanBeExcavatedBy saying no, a rolled-back
+// transaction — arrives as a bridge exception, and without the flag an MCP
+// client reads it as a successful call whose text happens to start with
+// "Error:". A write that did not happen must not look like one that did.
+
+import { z } from "zod";
+import { clampLimit, DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT } from "./read.js";
+
+// The bridge refuses more than this per inspect call rather than clamping: a
+// silently shortened inspection reads as a complete one.
+export const MAX_INSPECT_IDS = 500;
+
+export function registerQualityTools(server, bridge) {
+  server.tool(
+    "revit_inspect_elements",
+    "Measure elements: everything revit_get_elements leaves out. Per element — id, name, uniqueId, Revit class, category, typeId, typeName, level, hostId, pinned, groupId, its location (a point, or a curve's endpoints), its model bounding box and its material ids. A floor also reports its level, height offset and the closed loops of its top face; a toposolid (or legacy topography) reports its shape vertices with absolute positions, which is the only way to see the grades paving and planting sit on; a family instance reports its symbol, facing and hand vectors and the Z it ACTUALLY sits at. All coordinates are absolute model feet. Ids with no element come back in missingIds — nothing is dropped silently. Max 500 ids per call. With include_parameters, every parameter also reports its own id and BuiltInParameter name, and duplicateParameters lists the names Revit uses TWICE on one element (a family instance has two called 'Level', one read-only) — read that before writing anything by name with revit_set_parameters.",
+    {
+      ids: z
+        .array(z.number().int())
+        .min(1)
+        .max(MAX_INSPECT_IDS)
+        .describe(
+          `Element ids to inspect (max ${MAX_INSPECT_IDS} — over that is rejected, not truncated)`,
+        ),
+      include_parameters: z
+        .boolean()
+        .default(false)
+        .describe(
+          "Also return every instance parameter, each with its parameter id and built-in name, plus duplicateParameters for names Revit uses more than once. Off by default: it is hundreds of lines per element when three of them were the question.",
+        ),
+      include_geometry: z
+        .boolean()
+        .optional()
+        .describe(
+          "Force vertex/segment lists on or off. Omit it and they come back whenever there are 500 or fewer, and collapse to a count plus a min/max Z above that. true asks for them anyway, capped at 500 with truncated: true.",
+        ),
+    },
+    async ({ ids, include_parameters, include_geometry }) => {
+      try {
+        // The tool arguments stay snake_case like every other tool's, but the
+        // bridge reads camelCase — map it here rather than on the C# side.
+        const result = await bridge.call("/elements/inspect", {
+          ids,
+          includeParameters: include_parameters,
+          includeGeometry: include_geometry,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: `Error: ${error.message}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_move_elements",
+    "Move elements by a vector in feet — lift furniture out of a slab, shift a tree off a path — without rebuilding them. DRY RUN BY DEFAULT: dry_run is true unless you pass false, and a dry run opens no transaction and changes nothing. Either way every element comes back with before and after location AND bounding box, so you never have to guess where something ended up; on a real move the after is read back off the element, on a dry run it is arithmetic (afterSource says which). All-or-nothing: the whole batch moves in one transaction and one undo step, and the request is refused before anything is touched if any id is missing, pinned (the bridge will NOT unpin for you) or in a group. Nothing is ever deleted. A real move is MEASURED before it commits: Revit accepts a move it then does not apply — a family instance whose elevation comes from its level is the everyday case — so if any element did not take the displacement asked for, the whole request is rolled back with MOVE_NOT_APPLIED naming requested against actual, never reported as moved. Ids with nothing measurable come back in unverified.",
+    {
+      ids: z.array(z.number().int()).min(1).describe("Element ids to move"),
+      translation: z
+        .object({
+          x: z.number().describe("East/west offset in feet"),
+          y: z.number().describe("North/south offset in feet"),
+          z: z.number().describe("Vertical offset in feet — positive is up"),
+        })
+        .describe("How far to move, in feet (Revit internal units). Finite numbers only."),
+      dry_run: z
+        .boolean()
+        .default(true)
+        .describe(
+          "true (the default) measures and reports what the move would do without changing the model. Pass false to actually move.",
+        ),
+    },
+    async ({ ids, translation, dry_run }) => {
+      try {
+        const result = await bridge.call("/elements/move", {
+          ids,
+          translation,
+          dryRun: dry_run,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: `Error: ${error.message}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_excavate_toposolid",
+    "Cut a toposolid with the elements that should be sunk into it — a pool, a basement, a sunken path — using Revit's native Toposolid.ExcavateBy. This is the NON-DESTRUCTIVE way to make a floor or a pool clear the terrain: revit_flatten_toposolid rewrites the grades under a region and that ground never comes back, while an excavation is an association, so the surface keeps every vertex and the hole follows the element that made it. DRY RUN BY DEFAULT: dry_run is true unless you pass false, and a dry run opens no transaction. Every id is checked with Revit's own CanBeExcavatedBy before anything is opened, and the whole batch goes in one transaction and one undo step. The response reports the toposolid's volume before and after and the volume removed, plus the volume Revit attributes to each element — an element that was excavated but removed nothing does not actually overlap the surface. Nothing is ever deleted.",
+    {
+      toposolid_id: z
+        .number()
+        .int()
+        .optional()
+        .describe(
+          "The toposolid to cut. Optional only when the document has exactly one — with several, it is required, and the error lists them.",
+        ),
+      ids: z
+        .array(z.number().int())
+        .min(1)
+        .describe(
+          "Ids of the elements that cut the terrain (the pool, the floor, the mass) — not the toposolid itself",
+        ),
+      dry_run: z
+        .boolean()
+        .default(true)
+        .describe(
+          "true (the default) runs the CanBeExcavatedBy preflight and reports the current volume without changing the model. Pass false to actually excavate.",
+        ),
+    },
+    async ({ toposolid_id, ids, dry_run }) => {
+      try {
+        const result = await bridge.call("/toposolid/excavate", {
+          toposolidId: toposolid_id,
+          ids,
+          dryRun: dry_run,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: `Error: ${error.message}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_get_warnings",
+    "Read the warnings the model is carrying right now — Revit's own Review Warnings list. Each one carries the GUID of its failure definition (the only stable identity a warning kind has; the message text is localised), its severity, its message, the element ids it is about and any additional ids. Read-only. This is NOT revit_diagnostics: that one is what the bridge suppressed during your writes, this one is the standing state of the model. Answers with the full total, so paging with offset tells you what you have not seen.",
+    {
+      limit: z
+        .number()
+        .int()
+        .positive()
+        .default(DEFAULT_QUERY_LIMIT)
+        .describe(
+          `Max warnings to return (default ${DEFAULT_QUERY_LIMIT}, hard cap ${MAX_QUERY_LIMIT} — higher values are clamped, not rejected)`,
+        ),
+      offset: z
+        .number()
+        .int()
+        .min(0)
+        .default(0)
+        .describe("Warnings to skip, for paging through a noisy model"),
+    },
+    async ({ limit, offset }) => {
+      try {
+        const result = await bridge.call("/document/warnings", {
+          limit: clampLimit(limit),
+          offset,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: `Error: ${error.message}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  server.tool(
+    "revit_list_view_templates",
+    "List the view templates in the model: id, name, view type, and the parameters each template CONTROLS with their labels. Read-only. Check this before setting a scale, a display style or a category override on a view — a parameter the template controls is one the view cannot hold its own value for, which is why a setting you wrote reads back as something else.",
+    {},
+    async () => {
+      try {
+        const result = await bridge.call("/views/templates");
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: `Error: ${error.message}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+}