Skip to main content
Glama

ScanBIM MCP

by io.scanbimlabs
OverviewDiscussionsAdmin

detect_clashes

Run a first-pass bounding-box clash check between two element categories in a translated model. Element boxes are read from the APS Model Derivative properties endpoint; ScanBIM never estimates or synthesises geometry. If the model returns no element boxes for a category, the tool returns status 'unavailable' with the element counts it did find and runs NO clash pass - treat that as no result, not as zero clashes. On a model that does carry boxes it returns each overlapping pair with a severity, a suggested fix and a rework-hour estimate. This is an axis-aligned box pass with no tolerance and no clearance rule, so it is a triage aid, not a substitute for a Navisworks or ACC Model Coordination run. When to use: you want a first-pass coordination report between two MEP or structural trades (e.g. Ducts vs Structural Framing) for a model that has finished translating. When NOT to use: the model has not finished translating yet (call get_model_metadata first to confirm manifest.status=='success'), or you need clash detection between more than two categories — call this tool multiple times. APS scopes: data:read viewables:read Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh; 403 scope or resource permission denied; 404 URN not found or has no derivatives yet — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: READ-ONLY on APS. Inserts a row into D1 usage_log for analytics. Idempotent — repeated calls return the same clash set for a given model.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
model_idYesAPS URN returned by upload_model. Base64url-encoded Autodesk object ID starting with 'dXJu' (which decodes to 'urn:adsk.objects:os.object:...'). Unpadded.
category_aYesRevit/IFC category name (case-sensitive, exactly as it appears in the model properties). Common values: 'Ducts', 'Pipes', 'Electrical', 'Structural Framing', 'Structural Columns', 'Mechanical Equipment', 'Walls'.
category_bYesSecond Revit/IFC category to clash against category_a. Case-sensitive; must match a category present in the translated model's property set.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • changedInput schema / properties / category_a / description
      Previous value: -"First category (e.g. Ducts, Pipes, Structure, Electrical)"New value: +"Revit/IFC category name (case-sensitive, exactly as it appears in the model properties). Common values: 'Ducts', 'Pipes', 'Electrical', 'Structural Framing', 'Structural Columns', 'Mechanical Equipment', 'Walls'."
    • addedInput schema / properties / category_a / examples
      Added value: +[
+  "Ducts"
+]
    • changedInput schema / properties / category_b / description
      Previous value: -"Second category to clash against"New value: +"Second Revit/IFC category to clash against category_a. Case-sensitive; must match a category present in the translated model's property set."
    • addedInput schema / properties / category_b / examples
      Added value: +[
+  "Structural Framing"
+]
    • changedInput schema / properties / model_id / description
      Previous value: -"APS URN or model ID from upload_model"New value: +"APS URN returned by upload_model. Base64url-encoded Autodesk object ID starting with 'dXJu' (which decodes to 'urn:adsk.objects:os.object:...'). Unpadded."
    • addedInput schema / properties / model_id / examples
      Added value: +[
+  "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6c2NhbmJpbS1tb2RlbHMvMTcwMDAwMDAwMDAwMF9idWlsZGluZy5ydnQ"
+]
  2. First observed

TDQS

A4.5/5.0
Behavior5/5

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

No annotations are provided, so the description carries the full behavioral burden, and it delivers: it discloses the 'unavailable' status semantics with the 'treat as no result, not zero clashes' warning, idempotency, the D1 usage_log side effect, read-only behavior on APS, the no-tolerance/no-clearance limitation, and the caveat that it is not a substitute for Navisworks or ACC Model Coordination. This is comprehensive disclosure for a tool with zero annotation coverage.

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?

Well front-loaded with the core purpose before any caveats, and each section (when-to-use, errors, rate limits, side effects) earns its place for an agent handling APS failures. It runs long, and the rate-limit and error-list detail borders on verbose, but it is logically organized rather than bloated — a minor trim would make it near-perfect.

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?

For a 3-param tool with no annotations and no output schema, the description covers purpose, usage conditions, exclusions, errors, scopes, rate limits, and side effects thoroughly. The main gap is output shape: it notes each pair returns severity, suggested fix, and rework estimate, but gives no indication of result ordering, result-count limits, or pagination behavior for large clash sets.

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 100%, so the 3-parameter schema already documents model_id format, category examples, and case-sensitivity. The description adds marginal context beyond the schema (e.g., that missing category boxes yield 'unavailable'), but this is behavioral rather than parameter-specific. The schema does the heavy lifting here, so the baseline 3 is appropriate.

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 description uses a specific verb and resource: 'Run a first-pass bounding-box clash check between two element categories in a translated model.' It defines the mechanism (axis-aligned box pass), the sourcing of geometry from the APS Model Derivative endpoint, and explicitly scopes the tool as a triage aid rather than a full clash tool. This clearly distinguishes it from the viewing, rendering, and issue-creation siblings in the tool list.

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?

Explicit 'When to use' and 'When NOT to use' sections name the exact conditions and direct the agent to alternatives: call get_model_metadata first to confirm manifest.status=='success', and call this tool multiple times for more than two categories. This is unambiguous routing guidance that leaves nothing to inference.

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

All ScanBIM MCP toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources