Revit Model MCP

Overview Schema Source Related Servers Discussions Admin

Aggregate Elements

revit_aggregate_elements

Read-onlyIdempotent

Group Revit elements by fields like category or level to get counts, sums, and averages. Use for breakdowns rather than listing individual rows.

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.

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; 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.
`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
`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.

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?

Beyond the readOnly/idempotent annotations, the description discloses return shape ('matchedElements and groups containing keys, count...'), unit conventions, null handling, empty-result behavior, error cases for invalid names, and failure modes ('missing document, read failure or timeout'). It also documents multi-instance behavior, which is valuable context not present in annotations.

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?

The description is longer than average but dense with useful information: usage, return shape, units, errors, and multi-instance caveats. It opens with a clear one-line summary and each subsequent sentence earns its place, though there is minor repetition with 'after revit_list_catalog' and 'Call revit_list_catalog first'.

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 14-parameter aggregation tool, the description covers the essential workflow, output contract, units, edge cases, and failure semantics. An output schema exists, so return-value details need not be fully restated. The only notable omission is detailed per-parameter examples, but the schema and description together are sufficient for correct invocation.

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 64%, so the description must add meaning beyond the schema. It does: it clarifies group_by semantics, numeric aggregation units, and the area_scheme interaction for area totals. However, some detailed parameter behavior is already supplied in the schema, so the description adds strong strategic context rather than filling every parameter gap.

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?

The first sentence 'Summarize matching elements by one or two fields after revit_list_catalog' identifies a specific verb, resource, and scope. It also clearly distinguishes the tool's aggregation purpose from revit_query_elements, which is for 'individual rows', so an agent can tell them apart.

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?

The description explicitly says to 'Call revit_list_catalog first', states 'prefer this tool for counts and breakdowns', and warns to use 'revit_query_elements only for individual rows'. It also gives a concrete area-total strategy: '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