Nonica Revit MCP

Nonica Revit MCP — SKILL.md

Comprehensive reference for all Nonica Revit MCP tools.
Covers tool parameters, return shapes, and lessons learned from live testing.

Quick-start Workflow

1. Orient yourself          → get_active_view_in_revit
2. Find a category          → get_category_by_keyword("Wall")
3. Get elements             → get_elements_by_category(categoryId)
4. Inspect one element      → get_parameters_from_elementid(elementId)
5. Read a param in bulk     → get_parameter_value_for_element_ids(ids[], paramId)
6. Write / act              → set_parameter_value_for_elements / set_* tools

Tool Reference

GROUP 1 — Zero-parameter Context Tools

These require no input and are safe to call anytime for orientation.

⚠️ Lesson: get_model_categories can return hundreds of rows — expensive. Prefer get_category_by_keyword first.

GROUP 2 — Discovery / Navigation

get_category_by_keyword(keyword)

• Use first to find category IDs efficiently
• keyword must be in the model's language (check language field returned by any tool)
• Returns matching categories — often 2 results: the main category + its tags category

get_all_used_families_of_category(categoryId)

• Returns loadable family names + IDs for a category
• Does NOT include system families (walls, floors, etc.)

get_all_used_types_of_families(familyNames[])

• Returns all type IDs + names per family
• Works for both loadable AND system families
• familyNames must match exactly (case-sensitive)

get_all_elementids_for_specific_type_ids(list_elementIds[])

• Returns instance element IDs for each type ID
• ⚠️ Returns empty array for types that exist but have no placed instances — this is correct, not an error
• A type ID that returns [] means the type definition exists in the model but no instances have been placed
• MAX: 50 type IDs per request

get_all_elements_of_specific_families(familyNames[])

• Returns all instance IDs per family name
• More direct than type-based lookup when you want all instances of a family
• familyNames must match exactly; MAX: 30 names per request

get_elements_by_category(categoryId)

• Returns all instance element IDs for a category
• Fast — use this for bulk element discovery

get_all_elements_shown_in_view(viewOrSheetId)

• Works with views, schedules, and sheets
• ⚠️ WARNING: Causes token overflow on complex 3D views (output can exceed 60,000 characters on large models)
• Best used with: sheet IDs, schedule IDs, or simple plan views
• For 3D views with many elements, prefer get_elements_by_category instead

GROUP 3 — Element Properties

get_parameters_from_elementid(elementId)

• Always call this first on any new element type to discover parameter IDs
• Returns par_write_in_element + par_read_only_in_element, each with {Id, Name, Value}
• Note at end: "More as additional properties" → use get_all_additional_properties_from_elementid for API-level props
• Common built-in parameter IDs (consistent across all Revit models):
  • -1010106 → Comments (String, writable)
  • -1001203 → Mark (writable)
  • -1001362 → Head Height (doors/windows)
  • -1002002 → Family Name (read-only)
  • -1002001 → Type Name (read-only)
  • -1002108 → Host Id (read-only)
  • -1007401 → Sheet Number (sheets)
  • -1007400 → Sheet Name (sheets)

get_parameter_value_for_element_ids(list_elementIds[], idParameter)

• Bulk read of one parameter across many elements
• Get idParameter from get_parameters_from_elementid first
• MAX: 500 element IDs per request
• Groups elements with identical values together in output

get_all_additional_properties_from_elementid(elementId)

• Returns API-level (Revit DB class) properties — writable + read-only separated
• Examples for FamilyInstance: Pinned, HandFlipped, FacingFlipped, FromRoom, ToRoom, UniqueId, Location, CreatedPhaseId
• Use only when get_parameters_from_elementid doesn't expose what you need

get_additional_property_for_all_elementids(propertyName, list_elementIds[])

• Bulk read of one API-level property
• propertyName is case-sensitive and must match exactly (e.g., "Name", "Pinned")
• MAX: 500 IDs per request

GROUP 4 — Geometry

get_boundingboxes_for_element_ids(list_elementIds[])

• Returns [min XYZ, max XYZ] in feet for each element
• Optional: idSheet for sheet-space bounding boxes
• MAX: 500 IDs per request
• Use for arrangement, spacing, and collision checks

get_location_for_element_ids(list_elementIds[])

• Returns LocationPoint or LocationCurve per element
• Units: feet; rotation in radians
• ⚠️ Coordinates are Revit's internal axes — NOT screen-relative
• Use get_active_view_in_revit → screen_up_direction + screen_right_direction to interpret spatial relationships visually
• Does NOT work with floors
• MAX: 500 IDs per request

get_boundary_lines(list_elementIds[])

• Returns actual edge geometry as start/end point pairs
• Only works with: Walls, Floors, Rooms
• More precise than bounding boxes for spatial analysis
• MAX: 30 IDs per request

GROUP 5 — Type / Category Inspection

get_categories_from_elementids(list_elementIds[])

• Returns category ID + name for each element, grouped
• MAX: 1000 IDs per request

get_object_classes_from_elementids(list_elementIds[])

• Returns full Revit API class name (e.g., Autodesk.Revit.DB.FamilyInstance)
• Useful to determine which additional properties are available
• MAX: 1000 IDs per request

get_element_types_for_elementids(list_elementIds[])

• Returns {TypeId, TypeName} with the instance IDs that share each type
• MAX: 500 IDs per request

get_host_id_for_element_ids(list_elementIds[])

• Returns the host/tagged element ID for hosted elements
• Works with: doors, windows, tags, MEP fixtures
• Use to trace doors → walls, tags → tagged elements

get_material_layers_from_types(list_elementIds[])

• Returns material layers: {MaterialId, MaterialName, MaterialWidth} in mm
• ⚠️ Must receive TYPE IDs (WallType, FloorType, RoofType, CeilingType) — NOT instance IDs
• Workflow: get_element_types_for_elementids → take TypeId → pass to this tool
• MAX: 100 IDs per request

GROUP 6 — Worksets (Collaborative Models)

get_worksets_from_elementids(list_elementIds[])

• Returns workset assignment per element
• Graceful response if model is not workshared — returns friendly message
• MAX: 1000 IDs per request

get_worksharing_information_for_element_ids(list_elementIds[])

• Returns workset name, creator, owner, last changed by per element
• Graceful response if not workshared
• MAX: 100 IDs per request

GROUP 7 — Views, Sheets, Schedules

get_schedules_info_and_columns(list_elementIds[])

• Input: schedule element IDs (category OST_Schedules)
• Returns: schedule title, category, columns with {ParId, ParName, Heading, IsHidden}
• Chain with get_all_elements_shown_in_view + get_parameter_value_for_element_ids to read schedule data

get_viewports_and_schedules_on_sheets(list_elementIds[])

• Input: sheet IDs
• Returns: title block ID, sheet frame, viewports + schedule instances with their frames and referenced view IDs
• MAX: 100 IDs per request

get_graphic_filters_applied_to_views(list_elementIds[])

• Returns all view filters per view: filter ID, name, type (ParameterFilter), filtered categories
• MAX: 50 IDs per request

get_graphic_overrides_for_element_ids_in_view(viewId, list_elementIds[])

• Returns element-level graphic overrides (highest priority layer)
• Returns "Graphics were not overrided in the view." when using defaults — this is normal, not an error
• Also returns category-level overrides for the categories involved
• Priority: Element override > View filter override > Category override
• Does NOT work with elements in linked documents
• MAX: 100 IDs per request

get_graphic_overrides_view_filters(viewId, list_filterIds[])

• Returns filter-level graphic overrides (medium priority layer)
• Get filter IDs from get_graphic_filters_applied_to_views first
• MAX: 100 IDs per request

get_if_elements_pass_filter(filterId, list_elementIds[])

• Returns three lists: passing, not passing, invalid
• Useful for QA workflows — test elements against a view filter condition
• MAX: 1000 IDs per request

GROUP 8 — Family Stats

get_size_in_mb_of_families(list_elementIds[])

• Input: family element IDs (from get_all_used_families_in_model)
• Returns ordered list by file size + model file size
• ⚠️ Do NOT use with elements from linked documents
• Can be slow for large families
• MAX: 30 IDs per request
• Some families return "Cannot get file size" with size 0 — this is expected for in-place families or certain non-loadable types; not an error

GROUP 9 — Document Switching (Linked Models)

get_document_switched(elementId?, switchMainDoc?)

• Switch context to a linked Revit document
• elementId: ID of a RevitLinkInstance (optional, default -1)
• switchMainDoc: set true to switch back to the main document
• After switching, all subsequent tool calls operate in the switched document
• Always switch back with switchMainDoc: true when done

GROUP 10 — Non-Destructive SET Tools

Safe to use; visual or selection changes only.

set_user_selection_in_revit(list_elementIds[])

• Selects elements in Revit, visible to user
• Accepts element IDs, type IDs, OR category IDs
• Tip: pass a type ID to select all instances of that type — no need to expand to individual IDs first
• Overrides current selection

set_isolated_elements_in_view(list_elementIds[], viewId)

• Isolates elements in a view
• Accepts element IDs, type IDs, OR category IDs
• ⚠️ No reset/clear isolation tool exists in the MCP — user must manually reset in Revit (View tab → Reset Temporary Hide/Isolate)

set_graphic_overrides_for_elements_in_view(list_elementIds[], viewId, red, green, blue, clearGraphics?)

• Sets element color override in a view using RGB values (0–255)
• Set clearGraphics: true to reset element back to default appearance (RGB values ignored when clearing)
• Does NOT work with elements in linked documents

GROUP 11 — Destructive SET Tools

Always confirm with user before executing. Changes persist in the Revit model.

set_parameter_value_for_elements(list_elementIds[], idParameter, list_newValues[])

• Bulk-writes a parameter value across elements
• idParameter: get from get_parameters_from_elementid
• list_newValues: strings; include unit acronym for numeric values (e.g., "2.12 m", "5 ft", "90 °")
• Supply one value to apply the same to all; or match list length to list_elementIds for per-element values
• Returns StorageType, DataType, and a grouped summary of what was written

set_additional_property_for_all_elements(propertyName, list_elementIds[], list_newValues[])

• Writes an API-level property (e.g., "Pinned", "Name")
• propertyName is case-sensitive
• Returns expected_format in response — check this if write fails
• MAX: 500 IDs per request

set_copy_elements(list_elementIds[], mov_vect_X[], mov_vect_Y[], mov_vect_Z[])

• Copies elements with a translation vector in feet
• Hosted elements are copied with their host
• Use get_active_view_in_revit screen directions to compute correct X/Y vectors
• MAX: 100 IDs per request

set_movement_for_elements(list_elementIds[], mov_vect_X[], mov_vect_Y[], mov_vect_Z[])

• Moves elements by a translation vector in feet
• Hosted elements are projected/corrected onto their host
• List order of IDs must match list order of vectors
• MAX: 100 IDs per request

set_rotation_for_elements(list_elementIds[], axis_start_*, axis_end_*, list_angles[])

• Rotates elements around an axis defined by start + end points
• list_angles: radians; positive = counterclockwise
• Default axis: element's location point + Z axis (if axis not specified)
• MAX: 100 IDs per request

set_copy_view_filters(origen_viewId, list_filterIds[], target_viewIds[])

• Copies filter definitions + graphics from one view to others
• Get filter IDs from get_graphic_filters_applied_to_views

set_revisions_on_sheets(list_sheetIds[], list_revisionIds[], assignRevisions)

• Assigns (true) or unassigns (false) revisions to sheets
• Cannot unassign if RevisionClouds exist on the sheet or any views on it

set_delete_elements(list_elementIds[])

• Permanently deletes elements from the document
• Also deletes: hosted elements, annotations, and dependent sub-elements
• Returns IdsDeleted + IdsNotDeleted
• ⚠️ When deleting a view, Revit deletes the view + all its dependent elements (10 IDs deleted for a single 3D view)

GROUP 12 — Creation Tools (3-step workflow)

Always follow this sequence:

Step 1: create_tool_names_explorer()           → get list of 14 tool names
Step 2: create_tool_arguments_explorer([...])  → get argument signatures
Step 3: create_tools_invoker(toolName, {...})  → execute

Available creation tools and their key arguments:

Critical notes for creation tools:

• Grids: +X = East, +Y = North
• Sections: What's visible to the RIGHT when standing at sectbase_start looking toward sectbase_end
  • Sectbase along +X → View looks South
  • Sectbase along +Y → View looks East
• Tags: For list_ids — use category ID for all elements, type IDs for type-filtered, instance IDs for instance-filtered; never pass all instance IDs when a category/type ID works
• PDF export: folderpath must end with \\; order sheets by number when combining
• argumentIdsAndValues in create_tools_invoker: Must be a JSON object matching the argument names exactly

Common Workflows

Find and inspect all doors of a fire-rated type

1. get_category_by_keyword("Door")                       → categoryId (e.g. -2000023)
2. get_all_used_families_of_category(categoryId)         → family names + IDs
3. get_all_used_types_of_families(["<DoorFamilyName>"])  → TypeIds + names
   → identify fire-rated types by name (e.g. containing "MIN" or "FR")
4. get_all_elementids_for_specific_type_ids([typeId])    → instance IDs
5. get_parameters_from_elementid(firstInstanceId)        → discover param IDs
6. get_parameter_value_for_element_ids(instanceIds, -1001203)  → Mark values

Read schedule data

1. get_elements_by_category(-2000573)                  → schedule element IDs
   (or use OST_Schedules category)
2. get_schedules_info_and_columns([scheduleId])        → column ParIds
3. get_all_elements_shown_in_view(scheduleId)          → listed instance IDs
4. get_parameter_value_for_element_ids(instanceIds, paramId) → cell values

Color-highlight elements by condition

1. get_elements_by_category(categoryId)
2. get_parameter_value_for_element_ids(ids, paramId)   → filter by value
3. set_graphic_overrides_for_elements_in_view(matchingIds, viewId, R, G, B)
4. set_graphic_overrides_for_elements_in_view(matchingIds, viewId, 0,0,0, clearGraphics:true)  → reset

Get wall composition

1. get_elements_by_category(-2000011)                  → wall instance IDs
2. get_element_types_for_elementids(wallInstanceIds)   → wall TypeIds
3. get_material_layers_from_types(wallTypeIds)         → material layers in mm

Export sheets to PDF

1. get_elements_by_category(-2003100)                              → sheet IDs (OST_Sheets)
2. get_parameter_value_for_element_ids(sheetIds, -1007401)         → sheet numbers (sort)
3. create_tool_arguments_explorer(["create_pdf_export_print"])     → confirm arg names
4. create_tools_invoker("create_pdf_export_print", {
     list_filenames: ["ProjectSheets.pdf"],
     list_viewids: [sheetId1, sheetId2, ...],  // sorted by number
     folderpath: "C:\\Users\\<username>\\Desktop\\",
     combineinonefile: true
   })

Important Gotchas & Lessons Learned

Response Format Reference

Every Revit MCP response includes this header:

type: ContextUpdate
source: RevitModel
timestamp: "2026-04-26T..."
language: English_USA           # ← use this for keyword searches
model_title: <Your Project Name>   # ← CHECK THIS EVERY RESPONSE — can change if user switches document
is_linked_doc: false            # ← true if switched to a linked doc

⚠️ Model switch detection: If model_title changes between calls, stop and call get_active_view_in_revit immediately. All IDs, family names, and view IDs from the previous model are invalid in the new one.

Common response patterns:

• Grouped by value: get_parameter_value_for_element_ids groups elements sharing a value
• Grouped by type: get_element_types_for_elementids groups instances under their type
• Grouped by category: get_categories_from_elementids groups instances under category
• Pass/fail/invalid: get_if_elements_pass_filter returns three separate lists
• Error "not overrided": Normal response from graphic override tools when defaults are in use

Category ID Quick Reference (Standard Revit Built-in IDs)

Nonica Revit MCP — Compatible with any Revit model