Revit Model MCP

Overview Schema Source Related Servers Discussions Admin

Query Elements

revit_query_elements

Read-onlyIdempotent

Query and paginate elements from an open Revit model using filters like category, level, and parameters; returns element IDs, values with units, and optional geometry.

Instructions

Read a page of matching element rows after revit_list_catalog.

Returns data with elements (id and values), fields, total, offset, limit and hasMore; values include availability, source and units when available. Lengths use mm, areas m2 and volumes m3; optional geometry uses model mm rounded to one decimal, and unavailable geometry is omitted. Use roomCenterMm for placement inside rooms; a bounding-box centre can lie outside the room. No matches or an offset beyond the result return elements=[]; advance offset while hasMore=true. Call revit_list_catalog first and prefer revit_aggregate_elements for counts and breakdowns. Invalid fields or filters, a missing document, read failure or timeout raise errors; partial data is not returned.

If more than one Revit instance is running, document is required; otherwise any instance may respond. Non-empty skipped means the answer is incomplete; skippedCount includes entries beyond the first 100.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`view`	No	Exact non-template view name from the views catalog, matched case-insensitively, to restrict the element collector. Default null searches the document without a view filter; combines with the other model filters.
`level`	No
`limit`	No
`phase`	No
`family`	No
`fields`	No
`offset`	No
`workset`	No
`document`	No	Case-insensitive substring of the target active document title or file name. Reads require exactly one matching instance; omitted document requires exactly one running instance. Zero or multiple matches fail before publishing. revit_list_instances returns all matching instances, or all running instances when omitted.
`type_name`	No	Exact type name to match, case-insensitively, combined with the other model filters. Default null applies no type filter; discover names with the family-types catalog.
`categories`	No
`process_id`	No	Exact positive Revit process ID. Takes precedence over document; if both are supplied they must agree.
`sort_field`	No	System field (e.g. id, category, level) or exact localized parameter name to sort before pagination; default id sorts by Revit element ID. Uses sort_direction, with element ID breaking ties for other fields.	id
`area_scheme`	No	Exact area-scheme name from the area-schemes catalog, matched case-insensitively. Default null applies no scheme filter; selecting a scheme restricts results to its areas and combines with the other filters.
`sort_direction`	No	Sort order: asc or desc, case-insensitively; default asc means ascending. Applies to sort_field before offset and limit.	asc
`timeout_seconds`	No	Positive integer seconds to wait for a result after pickup (120 when omitted); HTTP uses this as its response budget. Expiry raises an error, and increasing it does not override the add-in's execution limits.
`include_geometry`	No	Whether each query row includes available location, boundingBox and placed-room roomCenterMm coordinates in model millimetres, rounded to one decimal. Default false omits geometry; true increases the response size.
`parameter_filters`	No	AND-combined objects with an exact localized parameter name in parameter, an operator (equals, contains, greater, less, empty, not-empty, exists), and value for comparisons; default null applies no parameter filters. Numeric values use mm, m2, m3 or other document display units; contains requires text, and empty/not-empty/exists need no value.
`pickup_timeout_seconds`	No	Positive integer seconds to wait for the add-in to pick up a local or SSH job (300 when omitted); ignored over HTTP. A pickup timeout raises an error but the pending job may still execute later.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.7.0Sep 30, 2026

changedInput schema / properties / document / description

Previous value: -"Case-insensitive substring of the target active document title or file name; default null leaves requests unaddressed, so any instance may respond. Use a unique substring with multiple instances; revit_list_instances instead returns all matching instances, or all instances when omitted."New value: +"Case-insensitive substring of the target active document title or file name. Reads require exactly one matching instance; omitted document requires exactly one running instance. Zero or multiple matches fail before publishing. revit_list_instances returns all matching instances, or all running instances when omitted."

addedInput schema / properties / process_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Exact positive Revit process ID. Takes precedence over document; if both are supplied they must agree.",
+  "title": "Process Id"
+}

Changed10 schema fields changedv0.1.1Sep 15, 2026

addedInput schema / properties / area_scheme / description

Added value: +"Exact area-scheme name from the area-schemes catalog, matched case-insensitively. Default null applies no scheme filter; selecting a scheme restricts results to its areas and combines with the other filters."

addedInput schema / properties / document / description

Added value: +"Case-insensitive substring of the target active document title or file name; default null leaves requests unaddressed, so any instance may respond. Use a unique substring with multiple instances; revit_list_instances instead returns all matching instances, or all instances when omitted."

addedInput schema / properties / include_geometry / description

Added value: +"Whether each query row includes available location, boundingBox and placed-room roomCenterMm coordinates in model millimetres, rounded to one decimal. Default false omits geometry; true increases the response size."

addedInput schema / properties / parameter_filters / description

Added value: +"AND-combined objects with an exact localized parameter name in parameter, an operator (equals, contains, greater, less, empty, not-empty, exists), and value for comparisons; default null applies no parameter filters. Numeric values use mm, m2, m3 or other document display units; contains requires text, and empty/not-empty/exists need no value."

addedInput schema / properties / pickup_timeout_seconds / description

Added value: +"Positive integer seconds to wait for the add-in to pick up a local or SSH job (300 when omitted); ignored over HTTP. A pickup timeout raises an error but the pending job may still execute later."

addedInput schema / properties / sort_direction / description

Added value: +"Sort order: asc or desc, case-insensitively; default asc means ascending. Applies to sort_field before offset and limit."

addedInput schema / properties / sort_field / description

Added value: +"System field (e.g. id, category, level) or exact localized parameter name to sort before pagination; default id sorts by Revit element ID. Uses sort_direction, with element ID breaking ties for other fields."

addedInput schema / properties / timeout_seconds / description

Added value: +"Positive integer seconds to wait for a result after pickup (120 when omitted); HTTP uses this as its response budget. Expiry raises an error, and increasing it does not override the add-in's execution limits."

addedInput schema / properties / type_name / description

Added value: +"Exact type name to match, case-insensitively, combined with the other model filters. Default null applies no type filter; discover names with the family-types catalog."

addedInput schema / properties / view / description

Added value: +"Exact non-template view name from the views catalog, matched case-insensitively, to restrict the element collector. Default null searches the document without a view filter; combines with the other model filters."

First observedSep 15, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only/idempotent/non-destructive, and the description goes well beyond them: it discloses failure modes ("invalid fields or filters, a missing document, read failure or timeout raise errors"), guarantees no partial data, and describes multi-instance document requirements and skipped/skippedCount semantics. This is exactly the extra context an agent needs to invoke safely.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core read/pagination contract in tight sentences, then back-loads secondary operational context (multi-instance handling, skipped counts). Every sentence carries information, though the density and the trailing multi-instance note are slightly heavy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 19-parameter, stateful query tool, the description covers prerequisites, pagination, units, error behavior, and document selection, and it still summarizes the return shape even though an output schema exists. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 58%, so the schema documents many parameters, but the description adds cross-cutting semantics the schema lacks: a global unit convention (mm, m2, m3), the meaning of roomCenterMm versus a bounding-box centre, and the offset/hasMore pagination contract. It does not add meaning for the undocumented filters (level, phase, family, workset, categories), so it falls short of fully compensating.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Read a page of matching element rows") and anchors it to the workflow start ("after revit_list_catalog"). It explicitly differentiates from siblings by naming revit_list_catalog and revit_aggregate_elements, so an agent can tell it apart from the catalogue and aggregation tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit sequencing ("Call revit_list_catalog first") and an alternative for a different need ("prefer revit_aggregate_elements for counts and breakdowns"). It also states the pagination loop condition ("advance offset while hasMore=true") and the termination case ("offset beyond the result return elements=[]").

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server