Skip to main content
Glama
sharafutdinovdi

Revit Model MCP

Query Elements

revit_query_elements
Read-onlyIdempotent

Query Revit model elements with filters such as category, family, level, view, and parameters. Returns matching rows, units, optional geometry, pagination, and skip details.

Instructions

Read a page of matching element rows. Lengths use mm, areas m2, volumes m3; optional geometry is in model mm. roomCenterMm is a point inside the room, a bounding-box centre can lie outside it. hasMore=true means further pages exist. A non-empty skipped list means the result is incomplete; skippedCount counts all skipped entries.

Input Schema

NameRequiredDescriptionDefault
viewNoExact non-template view name; limits the search to that view.
levelNo
limitNo
phaseNo
familyNo
fieldsNo
offsetNo
worksetNo
documentNoTitle or file name substring of the target document; needed when several Revit instances run.
type_nameNoExact type name, case-insensitive.
categoriesNo
process_idNoRevit process ID; takes precedence over document.
sort_fieldNoSystem field (e.g. id, category, level) or exact localized parameter name to sort by; default id.id
area_schemeNoExact area-scheme name, case-insensitive.
sort_directionNoasc (default) or desc, case-insensitive.asc
timeout_secondsNoSeconds to wait for a result (default 120).
include_geometryNoInclude location, boundingBox and roomCenterMm in model mm. Default false; true enlarges the response.
parameter_filtersNoAND-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.
pickup_timeout_secondsNoSeconds to wait for the add-in to pick up the job (default 300); unused over HTTP.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed34 schema fields changedv0.10.0
    • 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"
    • removedInput schema / properties / fields / title
      Removed value: -"Fields"
    • changedInput schema / properties / include_geometry / description
      Previous 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."New value: +"Include location, boundingBox and roomCenterMm in model mm. Default false; true enlarges the response."
    • removedInput schema / properties / include_geometry / title
      Removed value: -"Include Geometry"
    • removedInput schema / properties / level / title
      Removed value: -"Level"
    • addedInput schema / properties / limit / minimum
      Added value: +1
    • removedInput schema / properties / limit / title
      Removed value: -"Limit"
    • addedInput schema / properties / offset / minimum
      Added value: +0
    • removedInput schema / properties / offset / title
      Removed value: -"Offset"
    • 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 / sort_direction / description
      Previous value: -"Sort order: asc or desc, case-insensitively; default asc means ascending. Applies to sort_field before offset and limit."New value: +"asc (default) or desc, case-insensitive."
    • removedInput schema / properties / sort_direction / title
      Removed value: -"Sort Direction"
    • changedInput schema / properties / sort_field / description
      Previous 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."New value: +"System field (e.g. id, category, level) or exact localized parameter name to sort by; default id."
    • removedInput schema / properties / sort_field / title
      Removed value: -"Sort 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_query_elementsArguments"
    • removedOutput schema / title
      Removed value: -"revit_query_elementsDictOutput"
  2. Changed2 schema fields changedv0.7.0
    • 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"
      +}
  3. Changed10 schema fields changedv0.1.1
    • 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."
  4. First observed

TDQS

B3.4/5.0
Behavior4/5

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

Annotations already declare read-only, idempotent and non-destructive, so the bar is low, and the description still adds real behavior: unit conventions (mm, m2, m3, model mm for geometry), the semantic distinction between roomCenterMm and a bounding-box centre, and pagination/completeness signals (hasMore, skipped/skippedCount). It does not disclose timeout/long-running job behavior even though two timeout parameters exist.

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 the core action, then a series of short factual clauses; each sentence carries distinct information. The dense notation (roomCenterMm, skippedCount) is efficient though terse, and nothing is redundant.

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

Completeness3/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 need not be described, and the description usefully explains paging and incompleteness semantics. However, for a 19-parameter, zero-required-parameter query tool, it leaves the agent without guidance on filter construction, document targeting or timeout trade-offs.

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?

With 19 parameters and only 58% schema description coverage, several inputs (level, phase, family, fields, workset, categories, limit/offset) carry no meaning in either place. The description's unit conventions partly help interpret geometry and parameter_filters values, but it adds no guidance on filters, targeting (document/process_id) or sort semantics.

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 resource ('Read a page of matching element rows') and makes the paginated nature explicit. It does not differentiate this tool from close siblings such as revit_view_elements, revit_aggregate_elements or revit_element_details, so an agent must infer which query tool fits.

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

Usage Guidelines2/5

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

There is no when-to-use guidance, no prerequisites, and no mention of alternative query tools (e.g. revit_view_elements, revit_aggregate_elements) or when this paged tool is preferable to them. Only result-interpretation hints (hasMore, skipped list) are given, which is not usage guidance.

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

Deploy Server

Other Tools