Tool reference

The default tool list contains 84 tools, about 26,450 tokens. The core,read selection contains 22 tools, about 6,730 tokens. These estimates come from build/tool_size.py; the tool list size table lists bytes and counts by toolset.

confirm_token is a two-step handshake with the AI app. The AI app is expected to show the action to you; Model MCP does not show its own dialog. The token does not prove human approval.

Toolsets

tools/list costs context in every MCP client that does not load tools on demand. Set REVIT_MCP_TOOLSETS (or start the server with --toolsets) to a comma-separated list to expose only some tools. core is always included, all exposes everything, and an unknown name stops the server with the list of valid names. A hidden tool cannot be called; the tools stay registered in tool-manifest.json, which lists each tool's toolset.

Toolsets limit visibility only. They are not a permission: read-only mode, confirmation tokens and the add-in's own checks apply to every listed tool.

Session tools revit_activate_view, revit_activate_document, revit_select, revit_show, revit_isolate (temporary view state) and revit_close_views do not change the model. Their MCP annotations are readOnlyHint=true and destructiveHint=false. Model-changing tools retain their action annotations. These hints describe model access; workstation locks and policy checks still apply.

The default is all, so existing setups see the same tools. Clients with a small tool budget, or that warn about many tools, should set REVIT_MCP_TOOLSETS=core,read (22 tools, about 6,730 tokens) and add actions, views-sheets or others when needed. The prompts and the coordinator guide name read tools; the batch prompt needs batch.

Toolset	Tools
core	revit_ping, revit_list_instances, revit_documents, revit_document_info, revit_ui_state, revit_set_read_only, revit_jobs, revit_cancel_job, revit_undo_last
read	revit_list_catalog, revit_aggregate_elements, revit_query_elements, revit_element_details, revit_list_relations, revit_model_health, revit_model_audit, revit_list_warnings, revit_links_status, revit_shared_coordinates, revit_parameter_fill_check, revit_model_snapshot, revit_schedule_data
actions	revit_set_parameter, revit_update_parameters, revit_move, revit_rotate, revit_copy, revit_mirror, revit_change_type, revit_delete, revit_run_actions
documents	revit_open_document, revit_activate_document, revit_new_document, revit_close_document, revit_save_document, revit_sync_document
views-sheets	revit_list_sheets, revit_list_views, revit_view_info, revit_view_summary, revit_view_elements, revit_view_warnings, revit_capture_elements, revit_export_view, revit_activate_view, revit_close_views, revit_create_view, revit_duplicate_view, revit_apply_view_template, revit_set_view_visibility, revit_override_graphics, revit_tag_elements, revit_create_schedule, revit_select, revit_show, revit_isolate, revit_create_sheet, revit_place_views_on_sheet
family	revit_family_audit, revit_edit_families, revit_load_family, revit_place_family, revit_place_families
links	revit_compare_link_datums, revit_align_link_datums, revit_remove_links
cad-mep	revit_link_cad, revit_walls_from_cad, revit_create_wall, revit_create_mep_run
export	revit_export, revit_export_nwc, revit_nwc_settings_check, revit_issue_register
batch	revit_batch_start, revit_batch_status, revit_batch_cancel, revit_batch_fetch, revit_build_report, revit_audit_report, revit_process_models
code	revit_execute_code, revit_api_lookup

Tool list size

cd server && uv run python ../build/tool_size.py measures the tools/list payload (compact JSON of every tool, bytes; tokens are bytes divided by 4, an estimate). Tool and parameter descriptions state plain behavior. The confirmation procedure, addressing rules and long-job handling live in the server instructions and the revit://guides/coordinator resource, not in each description.

Toolset	Tools	Bytes	About tokens
core	9	7,574	1,893
read	13	19,347	4,836
actions	9	11,103	2,775
documents	6	4,952	1,238
views-sheets	22	25,837	6,459
family	5	8,967	2,241
links	3	4,104	1,026
cad-mep	4	5,663	1,415
export	4	7,283	1,820
batch	7	8,149	2,037
code	2	2,821	705
all (default)	84	105,800	26,450
core,read	22	26,921	6,730

These measurements use the default tool schemas. Optional server arguments can increase the payload.

MEP routing, graphic overrides, view and sheet creation, element tagging, schedule creation, CAD linking and wall construction actions are listed in Action tools. revit_place_views_on_sheet accepts a sheet element ID (integer or numeric string), sheet number, or sheet name; an unmatched reference returns candidate sheets.

Revit-backed tools support local, SSH and HTTP transports. revit_build_report runs on the MCP client machine from snapshot files and needs no Revit transport or running instance. revit_capture_elements downloads a highlighted element PNG over local or SSH transport; HTTP is unavailable. revit_export_view downloads PNG through /views/{name}/image in HTTP mode. revit_list_instances reports the connected Revit process in HTTP mode.

Every addressed Revit-backed read tool accepts optional process_id (alias processId), a strict positive integer. It selects an exact Revit process and must agree with document when both are given. See batch collection.

Every Revit-backed read tool except revit_list_sheets, revit_ui_state, revit_export_view, revit_capture_elements, revit_issue_register, revit_list_instances and revit_family_audit accepts timeout_seconds=120 and document=null. The server environment variable REVIT_MCP_PICKUP_TIMEOUT_SECONDS configures the file-channel pickup timeout (default 300 seconds). revit_ui_state accepts only process_id. Family audit accepts timeout_seconds=600 and document=null. Timeouts are seconds; pickup timeout applies only to local and SSH transports. Every timeout argument is named timeout_seconds; defaults and limits differ per tool and are listed in the tool schema. revit_jobs(wait_seconds) is a wait, not a timeout. Arguments named output_path (a file) and output_dir (a directory) write on the machine that runs the MCP client, unless the description says the path is on the workstation. revit_export, revit_process_models exports and save.output_dir write on the workstation. save_as is a Revit Save As path on the workstation. Arguments without defaults in these tables are required. The query filters shared by aggregation and queries are categories, family, type_name, level, view, workset, phase, area_scheme and parameter_filters; each defaults to null.

Every successful Revit-backed read result returns top-level skipped and skippedCount. Each skipped entry has what and reason. An empty list means no fields were omitted. A non-empty list means the answer is incomplete. The list keeps the first 100 entries; skippedCount reports the uncapped total. revit_list_instances returns instances with empty diagnostics. Model health uses this common shape instead of a nested metric/error list. Links status also keeps each link's error and mirrors it in skipped.

Tool	Arguments beyond the common read options	Purpose
revit_ping	None	Check connectivity; returns data:"pong" and readOnly: { enabled, source, setBy, setAtUtc }.
revit_set_read_only	enabled, confirm_token=null	Control the shared workstation lock. Lock immediately. Unlock only after an explicit user request and confirmation with the returned token. Policy locks cannot be changed. See read-only mode.
revit_jobs	job_id=null, wait_seconds=40	List jobs, or wait up to 50 seconds for an action job (0 through 50, default 40; poll again for longer jobs). Returns progress or the original final action response.
revit_nwc_settings_check	settings_xml	Parse exporter XML on the Revit workstation without exporting; return values, mapping, notApplied and ignored.
revit_document_info	None	Read document, levels, area schemes and worksets.
revit_documents	include_linked=false	List every open document in one Revit process, including background documents; linked documents are excluded by default.
revit_ui_state	None	Read the active document and view, open UI views, up to 500 selected elements, and all open documents.
revit_list_catalog	section, name_contains=null, limit=200 (1 to 2000)	Discover names with a case-insensitive filter. Returns total before the limit and hasMore.
revit_aggregate_elements	group_by, sum_field=null, shared query filters	Group by one or two fields (group_by takes 1-2 items); return counts and optional sum/average.
revit_query_elements	Shared query filters, fields=null, offset=0, limit=100, sort_field="id", sort_direction="asc", include_geometry=false	Read a page of matching elements.
revit_list_sheets	include_unplaced_views=true, offset=0, limit=200, document=null; no timeout argument	Read sheets, title blocks, revisions, placed view IDs and unplaced views.
revit_list_views	view_type=null, name_contains=null	Find views in the active document.
revit_view_summary	view	Read view metadata and category counts.
revit_view_info	view (name or decimal ID)	Inspect view template controls, display settings, hidden categories, worksets, filters, links and temporary modes.
revit_capture_elements	element_ids, pixel_size=1600, padding_mm=1500, mode="3d", output_path=null, document=null; no timeout arguments	Capture 1-500 model elements highlighted red in a temporary 3D or plan view. Returns PNG image content and local path; the view is rolled back. Local/SSH only.
revit_export_view	view, pixel_size=1600, output_path=null, document=null; no timeout arguments	Download a PNG; pixel_size is 32-4000 pixels (Revit rejects smaller images) on the fitted image dimension.
revit_schedule_data	schedule, max_rows=500, offset=0	Read visible schedule columns and data rows with totalRows and truncated. Paging excludes heading rows. Rejects non-schedules.
revit_view_elements	view, categories=null, offset=0, limit=100	Read a page of elements in a view.
revit_element_details	element_id	Read instance/type parameters and geometry by unitless Revit ID; element_id must be at least 1.
revit_view_warnings	view	Read warnings involving elements in a view.
revit_list_warnings	warning_text=null, include_elements=false	Group warnings or inspect a specific warning group.
revit_list_relations	relation, source_id=null, source_name=null	Read membership or dependencies.
revit_list_instances	document=null; no timeout arguments	Return endpoint or heartbeat information in instances.
revit_model_health	output_path (optional)	Read model quality counts and top warnings; save an Excel health report on the MCP server machine.
revit_links_status	None	Read RVT, CAD and image status, paths and instance counts.
revit_shared_coordinates	None	Read base/survey points, sites and link transforms in mm and degrees. Refused for family documents.
revit_family_audit	families=null, detail="summary", timeout_seconds=600	Summary returns parameter counts and up to 20 unused parameter names, shared status, and purge candidates. detail="full" returns all parameter metadata with group IDs and groupName labels. ["*"] audits the first 200 editable families sorted by name; data.skipped lists each remaining name and reason, with skippedCount.
revit_parameter_fill_check	categories, parameters, level=null, workset=null, view=null, sample_limit=20, include_types=true	Count filled, empty and missing values; sample unitless element IDs.
revit_api_lookup	query, kind="search", limit=25, include_inherited=false, include_obsolete=true, document=null, process_id=null	Look up public types and members in the running Revit API.
revit_model_snapshot	parameter_rules=null, document=null, process_id=null	Read a schema version 1 project snapshot for batch audits.
revit_batch_start	paths=null, folder=null, recursive=false, parameter_rules=null, years=null, open_timeout_minutes=null	Start persistent read-only collection; see batch collection.
revit_batch_status	run_id	Read persisted run and model status.
revit_batch_cancel	run_id	Persist cancellation and stop unstarted models.
revit_batch_fetch	run_id, output_dir	Copy completed JSON snapshots to new local files.
revit_compare_link_datums	link, kinds=null (grids and levels), name_map=null (no renames), prefix="", suffix="", level_offset_mm=0, reuse_matching=true, tolerance_mm=0.5	Compare link grids and levels with host datums without modifying the model.
revit_issue_register	output_path, project, issues, pixel_size=900, document=null; no timeout arguments	Write a new local .xlsx review register with documents, severity totals, category chart, element rows and snapshots.
revit_build_report	snapshots_dir, output_path, previous_dir=null, findings=null; no Revit document or timeout arguments	Build a local .xlsx report from schema-v1 snapshots.

Pinned elements

pinned is a built-in boolean field read from Element.Pinned. Use it in revit_query_elements fields and revit_aggregate_elements group_by. Filter it with parameter_filters=[{"parameter":"pinned","operator":"equals","value":"true"}] (or "false"). It also supports exists, empty and not-empty; the field always has a value. Returned values use value="true" or "false" and numericValue=1 or 0.

List sheets

revit_list_sheets(include_unplaced_views=True, offset=0, limit=200, document=None) reads the active or addressed document. It returns data.sheets[{id,number,name,titleBlock,revisionCount,viewportCount,viewIds}], data.unplacedViews[{id,name,viewType}], and data.total, data.offset, data.limit, data.hasMore. The response envelope includes skipped and skippedCount. Failed item reads are reported there.

Sheets include placeholders and sort by number, then ID. Paging applies only to sheets. The limit accepts 1 to 5000. Total counts all sheets, including skipped rows. The title block is the type name of the first title block by ID, or null. Revision count includes all revisions on the sheet. Viewport count excludes schedules. View IDs include viewport views, schedules, and panel schedules, sorted and deduplicated.

Unplaced views are returned in full on every page, sorted by ID. Setting include_unplaced_views=False returns an empty list. Templates, sheets, browsers, internal views, and walkthroughs are excluded. Printable plans, elevations, sections, details, drafting views, 3D views, legends, and renderings are eligible. User schedules and panel schedules are included only if they have no placement on any sheet. Internal keynote and title block revision schedules are excluded. A legend or schedule placed on any sheet is never unplaced. This read opens no transaction.

Snapshot report

snapshots_dir contains regular *.json files directly in that directory. Files are read in filename order. output_path is a client-machine .xlsx path; missing parent directories are created and an existing file is never overwritten. previous_dir, when supplied, follows the same input rules and matches models by passport.title. Duplicate titles are rejected. findings is an optional list with model, severity, rule, element_ids (or elementIds) and recommendation; IDs are integers.

The sheets appear in this order: Summary, Warnings, Families, Parameters, Skipped, optional Changes, Findings. Summary has one row per current snapshot and uses passport.fileLastWriteUtc for File system time: this is the OS-observed file timestamp, not a save or sync timestamp. Revit Server change and user cells are blank when that data is absent. Warning and parameter sample IDs are comma-separated; truncated warning IDs have a marker. Parameters and Changes percentages are numeric values. Changes subtracts previous values from current values, with weighted model fill percent computed as total filled divided by total elements across parameter rows. Models without a previous match have blank deltas. Findings is header-only when omitted. Every sheet freezes the header and has an auto-filter.

Sheet	Columns
Summary	Model, Saved-in year, Runtime year, Upgraded, Workshared, Number of saves, File system time, Revit Server last change, Revit Server last user, Elements, Views, Sheets, Families, Family types, Links, Warnings total, Families total, In-place families, Family signals, Skipped
Warnings	Model, Warning, Count, Element IDs
Families	Model, Family, Category, In-place, Editable, Type count, Instance count, Warning count, Signals
Parameters	Model, Category, Parameter, Total, Filled, Empty, Missing, Fill percent, Sample IDs
Skipped	Model, What, Reason
Changes	Model, Warnings delta, Families delta, Fill percent delta, Number of saves delta
Findings	Model, Severity, Rule, Element IDs, Recommendation

revit_model_snapshot accepts an ordered list of {"category": "Walls", "parameter": "Mark"} rules. Each rule pairs one category and one parameter. No rules return empty parameterFill.rows. Warning groups contain at most 200 distinct affected element IDs, with elementIdsTruncated showing whether more exist. Closed user worksets add a skipped entry because element, family instance, warning attribution, and parameter fill results can be incomplete. For an ordinary open document, source.path, saved-in year, and file metadata come from the document's source file. A detached interactive document has no usable source file; its snapshot contains one source file skipped entry with reason detached document has no source file, and file-derived fields remain empty. fileLastWriteUtc is an operating system file observation, not a Revit save or sync time. passport.revitServer is always null and reserved for the later batch runner.

The settings_xml path rejects device paths, .. segments and UNC shares absent from trustedNetworkRoots; files over 1 MiB are refused before reading.

link accepts one linked instance ID or a case-insensitive substring of its instance or type name; ambiguous and unloaded links fail. Comparison transforms link geometry into host coordinates and reports aligned, differs, missing_in_host, host_only or unsupported. A same-name host datum matches first; a coincident differently named datum may match by geometry. Distances are millimetres and angles are degrees. Geometric alignment does not create a monitor relationship or later Coordination Review warnings.

revit_view_info returns id, name, type, isTemplate, template with controlled parameter names, detail level, display style, discipline, phase and phase filter, scale, crop and 3D section box in millimetres. It also returns the background type and colours where supported, category class toggles, individually hidden categories, filter visibility and enabled flags, Revit link visibility, and active temporary mode flags. worksets is null outside workshared documents. Link graphic overrides are inspected on Revit 2024 and later; earlier versions report instance and category hiding.

Family audit

On an open .rfa, omit families; the audit reads that family without saving it. In a project, pass 1-200 exact family names (case-insensitive) or ["*"] for every editable loadable family. The add-in opens each family with EditFamily and closes it without loading it back. In-place, non-editable and missing families have a skipped result with a reason. A project transaction must be closed before the call.

Each parameter reports scope, shared GUID, group type ID, formula, reporting status and use. Associations, formula substrings and dimension or array labels count as use. Formula matching is deliberately over-inclusive. An unused shared parameter has dataCarrierRisk:true because project schedules and tags can still depend on its values.

purgeable groups Revit's unused-element candidates by category. Coverage is full in Revit 2024 and later. In Revit 2022-2023, coverage is families-and-types; materials, patterns and styles are not included.

Coordinator checks. Call revit_model_health → revit_links_status → revit_shared_coordinates → revit_parameter_fill_check(categories=["Walls","Doors"], parameters=["Mark","Comments"]) before an export or hand-over. Category and parameter names use the model language; the fill check accepts 1-20 categories, 1-30 parameters and a sample limit of 1-100. Coordinator location and link lists are capped at 100 without pagination; locations are sorted by name and links by ID. pinned and viewSpecific are true when any instance of the reported type qualifies. Parameter names resolve through LookupParameter(name), which returns the first match by name; GUID and BuiltInParameter selection are unavailable. Paged reads that exceed their 60-second add-in budget return partial:true regardless of the client timeout. Family audit uses its own response budget and reports each attempted family. Image exports (revit_export_view, revit_capture_elements) are not cut at the 60-second budget: a written PNG produces a complete result (success:true) and output_path is honored; the client/response timeout still applies.

Offsets are zero-based row counts (at least 0); limits are positive row counts (at least 1). revit_query_elements and revit_view_elements clamp limits above 5000 to 5000. Lengths use mm, areas m2 and volumes m3 where metric fields are provided. Other numeric filter values follow document display units; returned query values carry a unit field when available. See the feed format for the distinction between filter inputs and numeric outputs. Parameter names come from the model's language; use revit_list_catalog(section="parameters") before filtering. output_path is a new file path on the MCP client's machine and never overwrites an existing file. The path is resolved on the machine that runs the MCP server, which is the client's machine for local and SSH setups; a path from another machine is not translated.

revit_element_details returns geometry alongside parameters in data. revit_query_elements(include_geometry=True) adds the same fields to each element in the returned page. The query flag defaults to False; default queries omit geometry. All coordinates use model axes in millimetres rounded to one decimal place.

Field	Contents
location	Point: type:"point", xMm, yMm, zMm. Curve: type:"curve", startMm, endMm, lengthMm.
boundingBox	minMm, maxMm, centerMm as [x,y,z] arrays from the element's model bounding box. Rooms use their own bounding box.
roomCenterMm	[x,y,z] from a placed room's location. Use roomCenterMm when placing something inside a room. A bounding box centre may lie outside a nonrectangular room.

Unavailable geometry is omitted.

Action job polling

Long actions and revit_jobs waits send progress notifications when the client requests a progress token. revit_run_actions publishes data.progress.steps with completed, total, and current (the last attempted action kind) after each step, including a failed step. The existing data.steps array retains per-step results. Completed steps count attempted steps; the final committed and rolledBack fields determine whether changes remain in the model. Long actions may return status:"running", jobId, progress, and partial per-model results. Call revit_jobs(job_id=jobId, wait_seconds=40) until the original final action response is returned. The action may already have changed the model; do not resubmit it while it runs. Action results remain available for 24 hours across MCP server restarts; see result retention. See long action jobs for cancellation and retention.

Issue register

output_path requires a new .xlsx path on the MCP server machine. Parent directories are created; existing files are refused before contacting Revit. project accepts optional string fields name, model, reviewer, client, stage, date and a documents list of {title, reference, revision} objects. issues requires 1-60 objects with title, category, finding and severity (critical, major, minor, info). Optional fields are id (default ISS-001 onwards), requirement_source, requirement, recommendation, status (default Open), responsible, due, element_ids (up to 500 positive integers) and snapshot (3d, plan, none). Categories are free text; typical values are Information standard, Naming, Level of information need, Model health, Coordinates and levels, Classification, Spatial and Geometry. Snapshots default to 3d with element IDs and none otherwise. The workbook contains Cover, Summary, Register and Elements. The finding cell contains the issue title and finding; snapshots occupy the final column. Captures run sequentially for the first 25 eligible issues in severity order, with stable input order for ties. The remaining issues receive Snapshot skipped: limit of 25 per register. A 210-second capture budget reserves time within the 240-second client limit for writing the workbook. A capture failure receives Snapshot unavailable: <reason> and does not fail the register. Result fields are path, issueCount, snapshotCount, bySeverity and warnings.

Saved health report

revit_model_health(output_path="C:\\Reports\\health.xlsx") writes a new workbook on the machine running the MCP server. outputPath is an alias for output_path. The path must end in .xlsx, its parent directory must exist, and an existing file is refused. Without output_path, the response is unchanged. With output_path, the response adds workbook with path, snapshotCount and warnings. The workbook contains Health, Warnings and Counts sheets. All warning groups include affected element IDs; snapshots cover up to five groups with the highest counts, with at most 50 elements per capture. The total capture budget is 60 seconds; failed or skipped captures become warnings.

The Health sheet uses the following default review thresholds. These are review defaults, not project requirements. Unavailable metrics receive Review status.

Check	Pass threshold
Warnings	0
Views not on sheets	At most 20% of all views; 0% when there are no views
Unused family types	At most 300
In-place families	0
CAD imports	0
Unplaced rooms	0
Rooms not enclosed	0
Design options	0 at the stage under review
Images	At most 20
Model groups	At most 50

Errors and refusals

Every tool follows one rule.

Case	What the client gets
Invalid, missing or unknown argument, unknown batch run, unknown document, command execution timeout, failed read	An MCP tool error (isError) with a message.
Unavailable SSH, named pipe, or HTTP transport	A normal result with success:false, command, error, errorCode:"transport_unavailable", and retryable:true.
A refused or failed action, including read-only mode	A normal result with success:false, command, error and errorCode.
An action that needs confirmation	success:true with data.needsConfirmation:true, confirmationText and confirmToken. This is not an error.

A tool rejects an argument it does not declare and names it. If the argument is a former name, the message names the new one. Documented aliases such as timeoutSeconds are accepted.

Read errorCode for programmatic handling. Read-only messages identify the workstation lock and explain how to remove it.

errorCode	Meaning
read_only	Refused because the workstation user lock is on. The message names ribbon, chat, or file, its UTC time, and removal options.
policy_blocked	Refused by the machine policy an administrator set, for example a denied tool or disabled code execution. error starts with Blocked by organization policy:. See the policy reference.
transport_unavailable	Revit cannot be reached over SSH, a named pipe, or HTTP. retryable is true. Retry when the workstation or tunnel is back.
action_failed	The add-in tried the action and reported a failure. error holds the add-in's message.

New codes can appear in a minor release; treat an unknown code as a failed action. A timed-out action is a tool error, not a result: the action may have changed the model, so inspect it before retrying. The same rule covers revit_undo_last, revit_cancel_job, revit_batch_start and revit_batch_cancel. The last two start and stop Revit processes, so they are refused in read-only mode like any action; revit_batch_status and revit_batch_fetch stay available.

Model audits

Tool	Purpose
revit_model_audit	Read one addressed model against local YAML or JSON rules, inline rules or a builtin pack. Save immutable results and compare with earlier results. Toolset: read.
revit_audit_report	Build new XLSX and self-contained HTML files from a local audit result without Revit. Toolset: batch.

See Model audit for rule examples, packs, evidence limits, statuses, history paths and report columns. revit_model_audit accepts rules, rules_inline, compare_with="previous", save=true, timeout_seconds, document and process_id. revit_audit_report accepts audit, output and format="both" (xlsx, html or both).

For revit_issue_register, audit findings map to issues through the pure Python helper audit.to_register_issues(result): title stays title, category comes from pack, finding describes measured value and threshold, severity stays severity, and requirement_source and requirement come from reference. Only failed findings and partial findings with observed violations become issues. The existing register limits remain in force.

My tools

My tools stores parameterized C# procedures on the Revit workstation. The saved tool commands belong to the code toolset.

Tool	Purpose
revit_save_tool	Compile and store a confirmed revision.
revit_list_tools	List saved tools on the workstation.
revit_get_tool	Read a saved tool and its parameter schema.
revit_run_tool	Execute a saved revision with validated arguments.
revit_delete_tool	Delete a saved tool after confirmation.

List and get carry readOnlyHint; save and delete require confirmation, and run follows the saved mode and execute_code confirmation flow. Every saved tool command is unavailable wherever execute_code is disabled.