Model MCP

Overview Schema Source Related Servers Discussions Admin

Aggregate Elements

revit_aggregate_elements

Read-onlyIdempotent

Summarize matching Revit elements by one or two fields, with optional sum and average, to aggregate filtered model selections into counts and measurements.

Instructions

Summarize matching elements by one or two fields, with optional sum and average. Lengths use mm, areas m2, volumes m3. For area totals, group by level and select the area scheme. skipped means incomplete; skippedCount is the total skipped.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "group_by": "<group_by>"
    },
    "name": "revit_aggregate_elements"
  }
}

Input Schema

Name	Required	Description
`view`	No	Exact non-template view name; limits the search to that view.
`level`	No
`phase`	No
`family`	No
`workset`	No
`document`	No	Title or file name substring of the target document; needed when several Revit instances run.
`group_by`	Yes	One or two distinct fields (e.g. category, family, type, level) or exact localized parameter names.
`sum_field`	No	Numeric field or parameter name to sum and average per group; lengths in mm, areas m2, volumes m3.
`type_name`	No	Exact type name, case-insensitive.
`categories`	No
`process_id`	No	Revit process ID; takes precedence over document.
`area_scheme`	No	Exact area-scheme name, case-insensitive.
`timeout_seconds`	No	Seconds to wait for a result (default 120).
`parameter_filters`	No	AND-combined filters: parameter (exact localized name), operator (equals, contains, greater, less, empty, not-empty, exists) and value. Numbers use mm, m2, m3 or display units.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv2.0.0Nov 3, 2026

removedInput schema / properties / pickup_timeout_seconds

Removed value: -{
-  "default": 300,
-  "description": "Seconds to wait for the add-in to pick up the job (default 300); unused over HTTP.",
-  "type": "integer"
-}

Changed29 schema fields changedv0.10.0Oct 14, 2026

changedInput schema / properties / area_scheme / description

Previous 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."New value: +"Exact area-scheme name, case-insensitive."

removedInput schema / properties / area_scheme / title
```
Removed value: -"Area Scheme"
```
removedInput schema / properties / categories / title
```
Removed value: -"Categories"
```

changedInput schema / properties / document / description

Previous 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."New value: +"Title or file name substring of the target document; needed when several Revit instances run."

removedInput schema / properties / document / title
```
Removed value: -"Document"
```
removedInput schema / properties / family / title
```
Removed value: -"Family"
```

changedInput schema / properties / group_by / description

Previous 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."New value: +"One or two distinct fields (e.g. category, family, type, level) or exact localized parameter names."

addedInput schema / properties / group_by / maxItems
```
Added value: +2
```
addedInput schema / properties / group_by / minItems
```
Added value: +1
```
removedInput schema / properties / group_by / title
```
Removed value: -"Group By"
```
removedInput schema / properties / level / title
```
Removed value: -"Level"
```

changedInput schema / properties / parameter_filters / description

Previous 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."New value: +"AND-combined filters: parameter (exact localized name), operator (equals, contains, greater, less, empty, not-empty, exists) and value. Numbers use mm, m2, m3 or display units."

removedInput schema / properties / parameter_filters / title
```
Removed value: -"Parameter Filters"
```
removedInput schema / properties / phase / title
```
Removed value: -"Phase"
```

changedInput schema / properties / pickup_timeout_seconds / description

Previous 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."New value: +"Seconds to wait for the add-in to pick up the job (default 300); unused over HTTP."

removedInput schema / properties / pickup_timeout_seconds / title
```
Removed value: -"Pickup Timeout Seconds"
```

changedInput schema / properties / process_id / description

Previous value: -"Exact positive Revit process ID. Takes precedence over document; if both are supplied they must agree."New value: +"Revit process ID; takes precedence over document."

removedInput schema / properties / process_id / title
```
Removed value: -"Process Id"
```

changedInput schema / properties / sum_field / description

Previous 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."New value: +"Numeric field or parameter name to sum and average per group; lengths in mm, areas m2, volumes m3."

removedInput schema / properties / sum_field / title
```
Removed value: -"Sum Field"
```

changedInput schema / properties / timeout_seconds / description

Previous 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."New value: +"Seconds to wait for a result (default 120)."

removedInput schema / properties / timeout_seconds / title
```
Removed value: -"Timeout Seconds"
```

changedInput schema / properties / type_name / description

Previous 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."New value: +"Exact type name, case-insensitive."

removedInput schema / properties / type_name / title
```
Removed value: -"Type Name"
```

changedInput schema / properties / view / description

Previous 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."New value: +"Exact non-template view name; limits the search to that view."

removedInput schema / properties / view / title
```
Removed value: -"View"
```
removedInput schema / properties / workset / title
```
Removed value: -"Workset"
```

removedInput schema / title

Removed value: -"revit_aggregate_elementsArguments"

removedOutput schema / title

Removed value: -"revit_aggregate_elementsDictOutput"

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

A3.7/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: unit conventions (mm, m2, m3) for summed values and the meaning of the response fields 'skipped' (incomplete) and 'skippedCount' (total skipped), which tells the agent how to interpret partial results.

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?

Four sentences, front-loaded with the core operation, then units, then the area-totals recipe, then output caveats. Dense and largely waste-free, though the unit sentence duplicates what the sum_field schema description already says.

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

Completeness4/5

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

An output schema exists, so return shape needn't be explained, and the description still usefully clarifies the skipped/skippedCount semantics and unit conventions. For a 14-parameter read-only tool the coverage is solid, with the main gap being routing guidance against sibling query/schedule tools and behavior of the AND-combined parameter_filters.

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

Parameters3/5

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

Schema coverage is 64%, so roughly a third of parameters (level, phase, family, workset, categories) are undocumented in both places. The description adds meaning for sum_field units and clarifies that group_by takes one or two distinct fields, but it does not compensate for the undocumented filter parameters or explain interaction between parameter_filters and the scalar filters.

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

Purpose4/5

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

States a specific verb and output form ('summarize matching elements by one or two fields, with optional sum and average'), which is clearly a grouping/aggregation operation. It does not name or distinguish from close siblings like revit_query_elements or revit_schedule_data, so an agent cannot tell from the text alone when aggregation beats a plain query.

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

Usage Guidelines3/5

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

'For area totals, group by level and select the area scheme' gives one concrete conditional recipe, which is useful. Beyond that, usage is only implied: there is no statement of when to prefer this over revit_query_elements or revit_schedule_data, and no exclusion criteria.

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

Deploy Server