Skip to main content
Glama
sharafutdinovdi

Revit Model MCP

List Relations

revit_list_relations
Read-onlyIdempotent

List Revit model object membership or dependencies by relation type, including level rooms, area scheme elements, view template dependents, group elements, and nested families.

Instructions

Read model object membership or dependencies. relation is level-rooms, area-scheme-elements or view-template-dependents (with source_name), or group-elements or nested-family (with source_id). A non-empty skipped list means the result is incomplete; skippedCount counts all skipped entries.

Input Schema

NameRequiredDescriptionDefault
documentNoTitle or file name substring of the target document; needed when several Revit instances run.
relationYes
source_idNoRevit ID of the source group (group-elements) or family instance (nested-family).
process_idNoRevit process ID; takes precedence over document.
source_nameNoSource name, case-insensitive: a level (level-rooms), area scheme (area-scheme-elements) or view template (view-template-dependents).
timeout_secondsNoSeconds to wait for a result (default 120).
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. Changed15 schema fields changedv0.10.0
    • 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"
    • 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"
    • removedInput schema / properties / relation / title
      Removed value: -"Relation"
    • changedInput schema / properties / source_id / description
      Previous value: -"Positive integer Revit ID of the source group for group-elements or family instance for nested-family. Default null is valid for name-based relations; these two ID-based relations require a value."New value: +"Revit ID of the source group (group-elements) or family instance (nested-family)."
    • removedInput schema / properties / source_id / title
      Removed value: -"Source Id"
    • changedInput schema / properties / source_name / description
      Previous value: -"Exact, case-insensitive source name: a level for level-rooms, area scheme for area-scheme-elements, or view template for view-template-dependents. Default null is valid for ID-based relations; name-based relations require a value from the catalog."New value: +"Source name, case-insensitive: a level (level-rooms), area scheme (area-scheme-elements) or view template (view-template-dependents)."
    • removedInput schema / properties / source_name / title
      Removed value: -"Source Name"
    • 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"
    • removedInput schema / title
      Removed value: -"revit_list_relationsArguments"
    • removedOutput schema / title
      Removed value: -"revit_list_relationsDictOutput"
  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. Changed5 schema fields changedv0.1.1
    • 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 / 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 / source_id / description
      Added value: +"Positive integer Revit ID of the source group for group-elements or family instance for nested-family. Default null is valid for name-based relations; these two ID-based relations require a value."
    • addedInput schema / properties / source_name / description
      Added value: +"Exact, case-insensitive source name: a level for level-rooms, area scheme for area-scheme-elements, or view template for view-template-dependents. Default null is valid for ID-based relations; name-based relations require a value from the catalog."
    • 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."
  4. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description goes further by disclosing incompleteness semantics ('a non-empty skipped list means the result is incomplete; skippedCount counts all skipped entries'), which is exactly the kind of partial-result behavior an agent cannot infer from 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?

Three dense sentences with no filler; the core purpose comes first and the operational caveat last. The enumeration is telegraphic rather than prose, which is efficient here but slightly terse for a seven-parameter tool.

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 values need not be spelled out, yet the description still explains the skipped/skippedCount fields that signal partial results. Relation values and their source parameter pairings are covered; only cross-tool routing guidance is absent.

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 86%, so the baseline is 3. The description earns above baseline by supplying the valid values for the otherwise undocumented, enum-less 'relation' parameter and by mapping each value to its required companion parameter (source_name vs source_id).

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 concrete read verb and resource ('Read model object membership or dependencies') and enumerates the five supported relation types, so an agent knows exactly what retrieves. It stops short of naming which sibling tools it supersedes or complements (e.g. revit_query_elements, revit_list_views), so sibling differentiation relies on inference.

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?

The parenthetical pairings ('with source_name', 'with source_id') give conditional guidance on which companion parameter each relation value requires, which is genuinely useful. However, there is no statement of when to prefer this tool over alternatives like revit_query_elements or revit_view_elements, and no exclusions.

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