Revit Model MCP

Overview Schema Source Related Servers Discussions Admin

Aggregate Elements

revit_aggregate_elements

Read-onlyIdempotent

Group and summarize matching Revit elements by one or two fields after revit_list_catalog. Returns counts plus optional sums, averages, and units.

Instructions

Summarize matching elements by one or two fields after revit_list_catalog.

Returns data with matchedElements and groups containing keys, count and optional numericCount, sum, average and unit. Lengths use mm, areas m2 and volumes m3; groups without numeric values have null sum and average. No matches return groups=[]; invalid field or filter names raise errors even for empty results. Call revit_list_catalog first; prefer this tool for counts and breakdowns, and revit_query_elements only for individual rows. For area totals, group by level and select the area scheme. A missing document, read failure or timeout raises an error; 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
`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
`phase`	No
`family`	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.
`group_by`	Yes	Required list of one or two distinct system fields (e.g. category, family, type, level) or exact localized parameter names from the catalog; no default. Each combination produces a count, with numeric totals added by sum_field.
`sum_field`	No	Numeric system field or exact localized parameter name to sum and average within each group. Default null omits numeric aggregation; lengths use mm, areas m2, volumes m3, and other quantities use the returned unit.
`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.
`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.
`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.
`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"
+}

Changed9 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 / group_by / description

Added value: +"Required list of one or two distinct system fields (e.g. category, family, type, level) or exact localized parameter names from the catalog; no default. Each combination produces a count, with numeric totals added by sum_field."

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 / sum_field / description

Added value: +"Numeric system field or exact localized parameter name to sum and average within each group. Default null omits numeric aggregation; lengths use mm, areas m2, volumes m3, and other quantities use the returned unit."

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 declare read-only/idempotent/non-destructive, and the description adds substantial behavior beyond them: no matches return groups=[], invalid field/filter names raise errors even on empty results, failures (missing document, read failure, timeout) error out with no partial data, and skipped/skippedCount signals incompleteness with a 100-entry cap. It also resolves multi-instance ambiguity.

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-loaded with purpose, then return shape, then usage routing and error semantics. Dense lines but each carries distinct information; the only mild cost is the slightly sprawling list of error/edge cases relative to the core aggregation purpose.

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?

An output schema exists, so the description need not explain return structure, yet it still documents units, error behavior, instance selection, and skipped semantics. For a 15-parameter aggregation tool with one required field, this covers everything an agent needs to call it correctly.

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 67%, and the description adds real meaning: group_by takes one or two distinct fields, sum_field controls numeric aggregation, and it documents unit conventions (mm/m2/m3) and null sum/average for non-numeric groups. These supplement rather than merely repeat the schema.

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+resource (summarize matching elements by one or two fields) and clarifies it produces counts/breakdowns rather than rows. Explicitly distinguishes itself from the sibling revit_query_elements, which the agent can use to pick the right tool without opening schemas.

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 a hard prerequisite (call revit_list_catalog first), a preference rule ('prefer this tool for counts and breakdowns'), and the alternative condition ('revit_query_elements only for individual rows'). It also names a prerequisite for a specific case (for area totals, group by level and select the area scheme).

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

Deploy Server