ScanBIM MCP
Server Details
AI Hub for AEC — 50+ 3D formats, clash detection, ACC integration via Autodesk Platform Services.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.8/5 across 19 of 19 tools scored.
Each tool targets a distinct operation: ACC management, model handling, clash detection, rendering, and XR sessions. Descriptions clearly differentiate when to use each, with minimal overlap.
Most tools follow a verb_noun pattern with domain prefixes (acc_, get_, list_, xr_). Minor deviations like 'lumion_render' and 'twinmotion_render' swap the order, but the overall pattern is consistent.
19 tools cover a comprehensive BIM workflow from upload to viewing, clash detection, rendering, and XR. Slightly above the typical 3-15 range, but each tool earns its place.
Core CRUD for models and ACC items is present, but missing update/delete operations for both models and ACC issues/RFIs. Rendering and XR are included but still stubs.
Available Tools
19 toolsacc_create_issueAInspect
Create a real issue (punchlist/QC item) in ACC Build's Issues module via the APS Construction Issues v1 API. Returns the ACC-generated issue_id which can be linked back to a model URN or a detected clash. When to use: detect_clashes flagged a critical clash, or a field user reports a QC defect, and you want to track it in ACC for assignment and closeout. When NOT to use: you want to file a formal information request between trades — use acc_create_rfi instead. You want a note on a model element — that is a markup, not an issue. APS scopes: data:read data:write account: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 (app not provisioned for the project's ACC account); 404 project_id not found — check the ID (strip any leading 'b.'); 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: NON-IDEMPOTENT. Creates a new ACC issue each call (repeated calls create duplicates). Inserts a row into D1 usage_log.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Short human-readable issue title, 1-255 chars. Shows up as the headline in ACC Issues UI. | |
| due_date | No | ISO 8601 calendar date (YYYY-MM-DD). Time component is ignored by ACC. | |
| priority | No | ACC issue priority. Defaults to 'medium' if omitted. | |
| project_id | Yes | ACC project ID in either 'b.<uuid>' or plain '<uuid>' form (the worker strips the 'b.' prefix before calling the Issues endpoint). Obtainable via acc_list_projects. | |
| assigned_to | No | ACC user ID (UUID) or email of the assignee. Pass null or omit to leave unassigned. | |
| description | Yes | Long-form issue body. Plain text; supports newlines. Include clash coordinates, trade impact, and suggested fix. | |
| linked_model_id | No | Optional APS URN linking this issue back to the source model. Stored for ScanBIM cross-referencing; not forwarded to ACC's linkedDocuments field. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for behavioral disclosure. It explicitly states the tool is non-idempotent and creates duplicates, describes side effects (D1 usage_log), and covers APS scopes, rate limits, and error codes comprehensively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured, with each paragraph serving a clear purpose: purpose, usage, scopes/limits/errors, side effects. It is appropriately front-loaded with the main purpose. A minor deduction for verbosity; could be slightly more terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, no output schema, no annotations), the description is remarkably complete. It covers usage guidelines, behavioral traits, parameter context, error handling, and side effects, providing everything an AI agent needs for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds extra context beyond schema descriptions, such as 'Obtainable via acc_list_projects' for project_id and 'Not forwarded to ACC's linkedDocuments field' for linked_model_id, raising the score to 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a real issue (punchlist/QC item) in ACC Build's Issues module via the APS Construction Issues v1 API, using specific verbs and resources. It distinguishes from siblings by explicitly mentioning acc_create_rfi for formal information requests and clarifying that markups are not issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use (detect_clashes flagged a critical clash or field user reports a QC defect) and when-not-to-use (for RFIs or markups) guidelines, naming alternative tools like acc_create_rfi.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
acc_create_rfiAInspect
Create a Request For Information in ACC Build's RFIs module via the APS Construction RFIs v1 API, in 'draft' status. Returns the ACC rfi_id. When to use: a trade or subcontractor needs formal information from the design team (unclear detail, conflicting spec, missing dimension) and you want a tracked paper trail. When NOT to use: the item is just a punchlist fix — use acc_create_issue. The question is internal to one trade — handle inside that trade's toolchain. APS scopes: data:read data:write account: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 (app not provisioned for the project's ACC account, or RFIs module not enabled); 404 project_id not found — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: NON-IDEMPOTENT. Creates a new draft RFI each call. Inserts a row into D1 usage_log.
| Name | Required | Description | Default |
|---|---|---|---|
| subject | Yes | Short RFI subject line, 1-255 chars. Appears as the RFI headline in ACC. | |
| priority | No | RFI priority. Defaults to 'medium'. | |
| question | Yes | Full question body sent to the design team. Plain text with newlines allowed. | |
| project_id | Yes | ACC project ID in 'b.<uuid>' or '<uuid>' form (the 'b.' prefix is stripped automatically). Obtainable via acc_list_projects. | |
| assigned_to | No | ACC user ID (UUID) or email of the responder. Pass null or omit to leave unassigned. | |
| linked_clash_id | No | Optional clash ID from detect_clashes output used to link this RFI back to the triggering clash. Stored for ScanBIM cross-referencing; not forwarded to ACC. | |
| linked_model_id | No | Optional APS URN of the model the RFI references. Stored for ScanBIM cross-referencing; not forwarded to ACC. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavioral traits: non-idempotent, creates draft each call, logs to usage_log, details API version, scopes, rate limits, and common errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (when to use, when not, scopes, rate limits, errors, side effects). Front-loaded with primary purpose. Slightly lengthy but each sentence contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-param tool with no output schema, the description covers all essential aspects: return value, usage guidance, error handling, side effects, and authentication requirements. Very thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds value by explaining edge cases (e.g., 'b.' prefix stripping, unassigned by omitting, cross-referencing fields not sent to ACC).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb (create), resource (RFI in ACC Build's RFIs module), status (draft), and return value (ACC rfi_id). It distinguishes from sibling tool acc_create_issue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear when-to-use (formal information request from design team) and when-not-to-use (punchlist fix or internal question), with specific alternative (acc_create_issue). Also lists scopes, rate limits, and error handling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
acc_list_issuesAInspect
List up to 50 issues from an ACC project, optionally filtered by status and priority. Returns a normalized array of {id, title, status, priority, due_date}. When to use: you need a dashboard view of open issues, to find a specific issue by metadata, or to check the status of previously created issues. When NOT to use: you want the full audit trail of a single issue — the ACC Issues UI or the per-issue endpoint is better. This tool caps at 50 results and does no pagination. APS scopes: data:read account: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 project_id not found — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: READ-ONLY. Inserts a row into D1 usage_log. Idempotent.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by ACC issue status. Accepted values: 'open', 'closed', 'in_review', 'draft'. Omit for all statuses. | |
| priority | No | Filter by priority: 'critical' | 'high' | 'medium' | 'low'. Omit for all priorities. | |
| project_id | Yes | ACC project ID in 'b.<uuid>' or '<uuid>' form (the 'b.' prefix is stripped automatically). Obtainable via acc_list_projects. | |
| assigned_to | No | Reserved for future filtering by assignee user ID or email. Currently not forwarded to the ACC API. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses read-only behavior, idempotency, usage log insertion, and error codes. It could additionally mention default ordering, but overall it provides substantial behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections and front-loaded purpose. While slightly lengthy, every sentence contributes meaningful information, and the organization aids readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is remarkably complete: it covers behavior, limitations, parameters, errors, rate limits, scopes, and side effects. It also mentions the return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by specifying accepted values for status and priority, form details for project_id, and flagging assigned_to as reserved/future. This clarifies usage beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List up to 50 issues from an ACC project' with optional filters and specifies the return structure. It distinguishes the tool from sibling tools like acc_create_issue and acc_list_rfis by focusing on listing issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use (dashboard view, find specific issue, check status) and when not to use (full audit trail), along with limitations (caps at 50, no pagination) and alternative per-issue endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
acc_list_projectsAInspect
List every Autodesk Construction Cloud (ACC) / BIM 360 project the configured APS 2-legged app has access to, flattened across all hubs, with hub_id, hub_name, project_id, project_name, and project type. When to use: you need a project_id to pass into acc_create_issue, acc_list_issues, acc_create_rfi, acc_list_rfis, acc_search_documents, or acc_project_summary. When NOT to use: you already have the b.xxxx project_id. This tool makes N+1 API calls (one per hub) so avoid calling it in tight loops. APS scopes: data:read account: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 (app not provisioned for any hub in ACC Account Admin → Custom Integrations); 404 no hubs found — check APS app provisioning; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: READ-ONLY. Inserts a row into D1 usage_log. Idempotent.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description fully covers behavior: it states READ-ONLY, idempotent, logs to usage_log, and lists possible errors with causes and suggested actions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, when to use/not use, scopes, rate limits, errors, side effects). Every sentence adds value, and it is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and no annotations, the description covers return fields, errors, rate limits, side effects, and behavioral traits comprehensively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline is 4. The description adds no parameter-specific detail because none are needed; it focuses on return fields and behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'List every Autodesk Construction Cloud (ACC) / BIM 360 project...' which includes a specific verb (list) and resource (projects), and clearly distinguishes from sibling tools that deal with issues, RFIs, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 are provided, with specific alternative tools named. It also warns about performance (N+1 API calls) and provides error handling guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
acc_list_rfisAInspect
List up to 50 RFIs from an ACC project, optionally filtered by status. Returns a normalized array of {id, subject, status}. When to use: you need a quick rollup of outstanding or answered RFIs on a project, or to find a specific RFI id. When NOT to use: you want the full response thread of a single RFI — use the ACC UI or per-RFI endpoint. This tool caps at 50 results and does no pagination. APS scopes: data:read account: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 (RFIs module may not be enabled on the project); 404 project_id not found — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: READ-ONLY. Inserts a row into D1 usage_log. Idempotent.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by RFI status. Common values: 'draft', 'open', 'answered', 'closed', 'void'. Omit for all. | |
| project_id | Yes | ACC project ID in 'b.<uuid>' or '<uuid>' form (the 'b.' prefix is stripped automatically). |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses read-only nature, rate limits, specific error codes with guidance, side effects (D1 usage log insert, idempotency), and that the tool is idempotent. This is comprehensive and honest.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections. Front-loaded with core action, then usage guidelines, then technical details. Every sentence earns its place; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description specifies the return format (normalized array of id, subject, status). Error handling and side effects are covered. For a simple list tool with 2 parameters, this is highly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds value by clarifying usage: status can be omitted for all, gives common status values, and explains project_id format and automatic 'b.' prefix stripping. This adds practical meaning beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists up to 50 RFIs from an ACC project with optional status filtering, specifying the resource, action, and constraints. It distinguishes from siblings by noting what it does not do (get full response thread) and implicitly differentiates from acc_create_rfi.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'When to use' and 'When NOT to use' sections, with clear conditions: use for quick rollup or finding an RFI ID; avoid for full response thread (recommends ACC UI or per-RFI endpoint). It also mentions the 50-result cap and no pagination.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
acc_project_summaryAInspect
Fetch a single ACC/BIM 360 project's full attributes (name, type, dates, address, hub) from the APS Data Management project endpoint. If hub_id is omitted, the first hub the app can see is used. When to use: you need name, type, or scope details for a single project before acting on it, or to confirm the project still exists. When NOT to use: you want the list of all projects — call acc_list_projects. You want issues/RFIs counts — call the list tools. APS scopes: data:read account: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 project_id or hub_id not found — check the IDs; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: READ-ONLY. Inserts a row into D1 usage_log. Idempotent.
| Name | Required | Description | Default |
|---|---|---|---|
| hub_id | No | Optional ACC hub_id (format 'b.<account-uuid>'). If omitted, the worker picks the first hub returned by /project/v1/hubs. | |
| project_id | Yes | Full ACC project_id including the 'b.' prefix, exactly as returned by acc_list_projects. Unlike the Issues/RFIs tools, this tool passes the ID through unchanged to the Data Management project endpoint. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description fully discloses behavioral traits: read-only, idempotent, inserts into D1 usage_log, lists all possible errors (401,403,404,429,5xx), APS scopes, and rate limits. Comprehensive transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with front-loaded main purpose, then when/not to use, errors, side effects. Every sentence adds value; no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description mentions returned attributes (name, type, dates, address, hub) which is adequate. Error handling and side effects are well covered. Could specify response format more, but sufficient for an API-fetch tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description largely repeats schema info. While it adds context about hub_id default and project_id unchanged from acc_list_projects, schema already covers these details. No significant added meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it fetches a single ACC/BIM 360 project's full attributes using specific verb 'Fetch' and resource 'single ACC/BIM 360 project'. Distinguishes from sibling tools like acc_list_projects for listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (need name/type/scope details, confirm existence) and when not to use (list projects -> acc_list_projects, issues/RFIs counts -> list tools). Also explains optional hub_id fallback behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
acc_search_documentsAInspect
Full-text search the ACC Docs module on a project for drawings, specs, submittals, and other documents matching a query string. Calls the APS Data Management v1 search endpoint scoped to a project. When to use: an agent needs to locate a spec section, a sheet, or a submittal by keyword (e.g. 'fireproofing', 'A-101', 'RFI 23'). When NOT to use: you already have the document URN/lineage — fetch it directly. You want the file contents — this returns metadata; download separately via Data Management. APS scopes: data:read account: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 (Docs module access required); 404 project_id not found — check the ID (note: this endpoint re-prepends 'b.' so pass the UUID form); 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: READ-ONLY. Inserts a row into D1 usage_log. Idempotent.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Free-text search string. Matched against document names and attributes. URL-encoded automatically by the worker. | |
| project_id | Yes | ACC project ID in 'b.<uuid>' or '<uuid>' form (the 'b.' prefix is stripped and re-prepended automatically for the Data Management API). | |
| document_type | No | Optional document type filter forwarded as filter[type]. Common values: 'drawing', 'spec', 'submittal', 'rfi', 'photo'. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully covers side effects: READ-ONLY, idempotent, logs to D1 usage_log. Also lists rate limits, error codes, and required APS scopes, giving agents complete behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections for purpose, usage guidelines, scopes, rate limits, errors, and side effects. Every sentence provides necessary information without redundancy, making it efficient for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers authentication, errors, rate limits, side effects, and parameter handling comprehensively. It lacks details on result format, but the tool's scope and behavior are fully described for effective selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters have schema descriptions (100% coverage). Description adds value by explaining that query is URL-encoded automatically, project_id can be in two forms, and document_type uses filter[type] with common values enumerated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool performs full-text search on ACC Docs module for drawings, specs, submittals, etc., backed by APS Data Management API. Specific examples and distinction from sibling tools (e.g., acc_list_issues) are provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use (agent needs to locate documents by keyword) and when NOT to use (if URN/lineage known, or if file contents needed), with alternative actions like fetching directly or downloading via Data Management.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
detect_clashesAInspect
Run a VDC-grade clash detection pass between two element categories in a translated model, returning each overlapping element pair with a severity (critical/warning), a trade-specific suggested fix, and an estimated rework hour count. Uses AABB bounding-box intersection on elements pulled from the APS Model Derivative properties endpoint, with a synthetic fallback if properties have not yet been computed. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | Yes | APS URN returned by upload_model. Base64url-encoded Autodesk object ID starting with 'dXJu' (which decodes to 'urn:adsk.objects:os.object:...'). Unpadded. | |
| category_a | Yes | 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'. | |
| category_b | Yes | Second Revit/IFC category to clash against category_a. Case-sensitive; must match a category present in the translated model's property set. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: read-only on APS, inserts a usage log row, idempotent, rate limits, error codes and handling, side effects. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (action, usage, scopes, limits, errors, side effects). Every sentence adds value, but the length could be slightly trimmed without losing information. Still very effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains return values (overlapping pairs, severity, fix, rework hours). Covers prerequisites, error handling, rate limits, idempotency, and side effects. Fully equips the agent for successful invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even with 100% schema coverage, the description adds crucial context: case-sensitivity of categories, common category values, and base64url encoding details for model_id. Goes beyond the schema to ensure correct parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool runs VDC-grade clash detection between two element categories in a translated model, returning overlapping pairs with severity, suggested fix, and rework hours. Distinguishes from siblings by specifying it's for two categories and when to use multiple calls for more categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use (first-pass coordination between two MEP/structural trades for finished translation) and when-not-to-use (model not finished translating, or need to clash more than two categories). Includes prerequisite check on manifest.status and alternative approach of calling multiple times.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_model_metadataAInspect
Fetch the APS Model Derivative manifest and metadata for a URN, including translation progress, derivative outputs, and a viewer URL. Use this to confirm a model has finished translating (manifest.status == 'success') before calling detect_clashes or opening the viewer. When to use: right after upload_model to poll translation progress, or later to inspect which viewable derivatives (SVF2, thumbnail, OBJ) are available. When NOT to use: you just want a link to share — call get_viewer_link. You want the actual element properties list — this tool returns the metadata index, not the full property collection. 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 job not yet submitted — 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. Idempotent.
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | Yes | APS URN (base64url-encoded Autodesk object ID, starts with 'dXJu', unpadded) as returned by upload_model. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses side effects (read-only on APS, logs to D1), errors, rate limits, and required scopes. This is comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is thorough but slightly long; however, every sentence adds value. Structure is well-organized with sections for purpose, usage, scopes, errors, side effects.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description details return values (manifest, metadata, translation status, derivative outputs, viewer URL). Also clarifies it returns a metadata index, not full properties, and provides error handling guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (model_id) with 100% schema coverage. Description adds meaning: explains it's a base64url URN starting with 'dXJu', unpadded, as returned by upload_model, which helps the agent construct correct input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches the APS Model Derivative manifest and metadata for a URN, including translation progress, derivative outputs, and a viewer URL. It distinguishes from siblings like detect_clashes and get_viewer_link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use (poll translation progress after upload, inspect derivatives) and when-not-to-use (get_viewer_link, element properties). Also mentions alternatives like detect_clashes and get_viewer_link.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_supported_formatsAInspect
Return the full matrix of supported input formats organized by subscription tier (free / pro / enterprise). Use to tell a user whether their file type is accepted before calling upload_model, or to surface pricing tier info. When to use: you need to validate a file extension or show a customer the supported format list. When NOT to use: you already know the extension is common (.rvt/.ifc/.nwd/.obj) — just call upload_model, which returns an 'Unsupported format' error for anything outside the matrix. APS scopes: none (static data). 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 (not applicable: no APS call); 403 scope or resource permission denied (not applicable); 404 not applicable; 429 rate limited — backoff and retry (worker-level only); 5xx APS upstream outage — retry with jitter (not applicable). Side effects: READ-ONLY and pure. Idempotent.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description thoroughly discloses behavioral traits: declares 'READ-ONLY and pure. Idempotent,' covers APS scopes (none), rate limits, errors, and side effects. This exceeds the burden for a tool without annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (purpose, usage, technical details). Information is front-loaded and relevant. Slightly verbose with rate limit and error details that are not applicable, but still earns its place for thoroughness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description fully covers purpose, usage guidelines, behavioral transparency, and technical constraints. No gaps remain for an agent to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so baseline is 4 per rule. The description adds no parameter-level detail (none exist), but it does not detract. The high schema coverage (100%) is trivial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool returns 'the full matrix of supported input formats organized by subscription tier.' It specifies the verb 'return' and the resource 'supported formats matrix,' and distinguishes itself from siblings like upload_model by explicitly stating its use case for validation before upload.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('tell a user whether their file type is accepted before calling upload_model, or to surface pricing tier info') and when NOT to use ('you already know the extension is common — just call upload_model, which returns an Unsupported format error'). Provides clear alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_viewer_linkAInspect
Return a shareable browser URL for the embedded APS viewer and a matching QR code for mobile/XR handoff. Does not require the model to be fully translated — the viewer page will poll the manifest. When to use: you need to hand a stakeholder a URL to see the 3D model in a browser, or print a QR for a jobsite. When NOT to use: you need the raw APS URN for programmatic API calls — use the model_id you already have instead. Do not use to check translation progress — call get_model_metadata. APS scopes: none (URL assembly only); the viewer page itself uses viewables:read data:read server-side via /token. 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 (only relevant when the viewer page loads); 403 scope or resource permission denied; 404 URN not found — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: READ-ONLY and pure. Idempotent: same model_id always returns the same URL + QR.
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | Yes | APS URN (base64url-encoded Autodesk object ID, starts with 'dXJu', unpadded) or the model_id returned from upload_model. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool is READ-ONLY, pure, and idempotent, explains that it does not require full translation, details APS scopes, rate limits, error codes, and side effects (none). This is comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (When to use, When NOT to use, APS scopes, Rate limits, Errors, Side effects). It is front-loaded with the main purpose and concise in each section; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 1 parameter, no output schema, and no annotations, the description covers all essential aspects: purpose, usage context, behavioral traits, error handling, rate limits, and relationships to siblings. It is fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (model_id) with a description that covers the URN format and origin. The tool description does not add new parameter-specific meaning beyond noting idempotency, which is more behavioral. With 100% schema coverage, baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns a shareable browser URL and QR code for the APS viewer. It specifies the verb 'Return', the resource (URL + QR), and the context (mobile/XR handoff). It also distinguishes from siblings by stating when not to use it (e.g., for checking translation progress, use get_model_metadata).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description has explicit 'When to use' and 'When NOT to use' sections, giving clear scenarios: handing a stakeholder a URL or printing a QR. It advises against using it for getting the raw APS URN or checking translation progress, and names the appropriate alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_modelsAInspect
List every object currently stored in the scanbim-models OSS bucket, with URN, size in MB, and a viewer URL for each. Returns the raw OSS inventory, not the D1 models table, so freshly uploaded items appear immediately. When to use: you need to enumerate previously uploaded models to find a URN, show an inventory, or pick one for a follow-up tool call. When NOT to use: you already know the exact URN — call get_model_metadata directly. This tool is not a search; it returns up to the OSS default page (typically first 10 objects unless OSS paginates). APS scopes: bucket:read data: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 bucket not found — no models have been uploaded yet (upload one first); 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: READ-ONLY. Idempotent.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Reserved for future filtering by file extension (e.g. 'rvt', 'ifc'). Currently informational only; the OSS listing is not filtered by this value. | |
| project_name | No | Reserved for future filtering by the D1 project_name column. Currently informational only; the OSS listing is not filtered by this value. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses read-only, idempotent, immediate visibility of fresh uploads, pagination behavior, APS scopes, rate limits, and error conditions comprehensively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections but slightly long. Could be trimmed slightly without losing essential info, but all content is relevant and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, yet description specifies return fields. Covers errors, rate limits, scopes, and side effects. Complete enough for an agent to invoke correctly with full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes both parameters, but description adds critical context that they are 'currently informational only' and do not filter OSS listing. This goes beyond schema and prevents misuse.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'list', resource 'objects in OSS bucket', and output details (URN, size, viewer URL). Distinguishes from sibling tools like get_model_metadata and search tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 with alternative tool (get_model_metadata). Also notes pagination limits and that it's not a search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
lumion_renderAInspect
Queue a Lumion-style architectural visualization still render with landscaping, people, vehicles, and atmospheric effects. Returns a render_id and preview_url; the render pipeline is a ScanBIM roadmap item so today this tool responds synchronously with a stub job descriptor. When to use: you want a more 'Lumion-flavored' render (lush entourage, vehicles, people) vs. Twinmotion's cleaner look. When NOT to use: you need real-time viewing — use get_viewer_link. You need video — use twinmotion_walkthrough. APS scopes: none today (render pipeline is ScanBIM-internal); viewables:read data:read will apply when live. 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 (will apply when pipeline is live); 403 scope or resource permission denied; 404 URN not found — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: NON-IDEMPOTENT. Each call mints a new render_id (lum_). Inserts a row into D1 usage_log.
| Name | Required | Description | Default |
|---|---|---|---|
| style | No | Overall visual preset. 'photorealistic' = full PBR, 'artistic' = painterly, 'sketch' = line-drawing overlay, 'aerial' = drone perspective. | |
| model_id | Yes | APS URN (base64url-encoded, starts with 'dXJu', unpadded) of the model to render. | |
| add_people | No | Populate animated/static human entourage. Defaults to true. | |
| add_vehicles | No | Populate cars, trucks, and other vehicles in parking/streets. Defaults to false. | |
| add_landscaping | No | Populate trees, shrubs, and ground cover appropriate to region. Defaults to true. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses non-idempotency, side effects (new render_id, usage log entry), rate limits, error codes, and that it's currently a synchronous stub. Comprehensive and honest.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections: purpose, when to use, limitations, scopes, rate limits, errors, side effects. Front-loaded with core purpose. Slightly verbose but each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters and no output schema, the description covers return values, error handling, rate limits, side effects, and future plans. Very complete and actionable for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions and examples for each parameter. The description adds overall context (e.g., returns render_id and preview_url) but does not significantly enhance parameter meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it queues a Lumion-style architectural render with specific elements (landscaping, people, vehicles, atmospheric effects). It distinguishes from sibling tools like twinmotion_render and mentions get_viewer_link for real-time viewing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (Lumion-flavored render) and when not to use (real-time viewing → get_viewer_link; video → twinmotion_walkthrough). Provides alternatives and context for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
twinmotion_renderAInspect
Queue a photorealistic Twinmotion-style still render of a translated model with time-of-day, weather, season, and resolution controls. Returns a render_id and preview_url; the actual render pipeline is a ScanBIM roadmap item (Week 5 buildout), so today this tool responds synchronously with a stub job descriptor. When to use: you want a scripted way to request a hero still for a proposal or client deck. When NOT to use: you need real-time interactive rendering — use get_viewer_link. You need a moving camera — use twinmotion_walkthrough. You expect the image file bytes back in the response — this tool returns a URL, not bytes. APS scopes: none today (render pipeline is ScanBIM-internal); viewables:read data:read will apply when the pipeline goes live. 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 (will apply when pipeline is live); 403 scope or resource permission denied; 404 URN not found — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: NON-IDEMPOTENT. Each call mints a new render_id (tm_). Inserts a row into D1 usage_log. When the pipeline is live it will create a rendering job on ScanBIM's compute backend.
| Name | Required | Description | Default |
|---|---|---|---|
| season | No | Vegetation and ground-cover preset. Defaults to 'summer'. | |
| weather | No | Sky and atmospheric preset. Defaults to 'clear'. | |
| model_id | Yes | APS URN (base64url-encoded, starts with 'dXJu', unpadded) of the model to render. | |
| resolution | No | Output image resolution. Defaults to '4k'. | |
| time_of_day | No | Sun angle preset driving lighting, shadows, and sky. Defaults to 'noon'. | |
| camera_preset | No | Named camera viewpoint (e.g. 'hero-exterior', 'lobby-entry'). Free-form string passed through to the render pipeline. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses behavioral traits: current stub behavior (synchronous, returns job descriptor), non-idempotency, side effects (new render_id, usage log entry), and future behavior when pipeline goes live. It also details error codes and rate limits, leaving no ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, usage guidelines, scopes, rate limits, errors, side effects). It is front-loaded with the main purpose. While comprehensive, it could be slightly more concise, but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains return values (render_id, preview_url) and stub behavior. It covers authentication, rate limits, error scenarios, side effects, and future roadmap. This is highly complete for a tool that is not fully live.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 6 parameters have descriptions in the schema (100% coverage). The tool description adds value by explaining the purpose of each parameter (e.g., 'Vegetation and ground-cover preset' for season), specifying defaults, and noting that camera_preset is a free-form string passed through. This exceeds the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queues a photorealistic still render with specific controls (time-of-day, weather, season, resolution) and returns a render_id and preview_url. It distinguishes itself from siblings like get_viewer_link and twinmotion_walkthrough by explicitly stating when not to use this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'When to use' and 'When NOT to use' sections, naming specific alternative tools (get_viewer_link, twinmotion_walkthrough). It also covers APS scopes and rate limits, providing comprehensive usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
twinmotion_walkthroughAInspect
Queue a cinematic Twinmotion-style fly-through video of a translated model. Returns a video_id and download_url; the render pipeline is a ScanBIM roadmap item so today this tool responds synchronously with a stub job descriptor. When to use: you want a short marketing or pre-con video scripted from an agent workflow. When NOT to use: you want real-time interactivity — use get_viewer_link. You want a still image — use twinmotion_render. APS scopes: none today (render pipeline is ScanBIM-internal); viewables:read data:read will apply when live. 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 (will apply when pipeline is live); 403 scope or resource permission denied; 404 URN not found — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: NON-IDEMPOTENT. Each call mints a new video_id (tmv_). Inserts a row into D1 usage_log.
| Name | Required | Description | Default |
|---|---|---|---|
| style | No | Animation and color-grade preset. 'cinematic' = orbits + tilts, 'technical' = orthographic pans, 'presentation' = slow lobby-to-penthouse. | |
| model_id | Yes | APS URN (base64url-encoded, starts with 'dXJu', unpadded) of the model to animate. | |
| duration_seconds | No | Video duration in seconds. Integer 10-600; defaults to 60 when omitted. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
In the absence of annotations, the description fully discloses behavioral traits: non-idempotence, synchronous stub behavior, side effects (new video_id, usage_log insert), error codes, rate limits, and APS scope requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections and front-loads the key purpose. Slightly verbose on details like rate limits and errors, but overall efficient for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description explains return values (video_id, download_url), covers errors, side effects, rate limits, and future state. Comprehensive for a 3-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all three parameters. The description adds minimal extra meaning beyond examples and brief style elaboration, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queues a cinematic Twinmotion-style fly-through video, returns a video_id and download_url, and distinguishes from siblings like twinmotion_render and get_viewer_link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'When to use' and 'When NOT to use' sections with specific alternative tools, giving clear guidance on appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
upload_modelAInspect
Ingest a 3D model from a public URL into APS OSS and kick off a Model Derivative translation job, returning the URN plus a browser viewer link and QR code. Supports 50+ formats: Revit (.rvt/.rfa), Navisworks (.nwd/.nwc), IFC, FBX, OBJ, SolidWorks, point clouds (E57/LAS/RCP), CAD (DWG/STEP/IGES), etc. When to use: you have a publicly downloadable 3D file (S3 presigned URL, GitHub raw, etc.) and need it translated to SVF2 so it can be viewed, measured, or clash-checked via other tools. When NOT to use: the file is only on a local disk or behind auth (fetch will fail) — first push it to a public URL. Do not call to re-translate a model already uploaded; call get_model_metadata instead. APS scopes: data:read data:write data:create bucket:read bucket:create 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 source file_url not reachable or bucket not found — check the ID; 409 bucket name conflict (bucket already owned by another app — pick a unique bucketKey); 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: NON-IDEMPOTENT. Creates the scanbim-models bucket if absent, uploads a new OSS object with a timestamped key (each call creates a distinct object even for the same input), submits a Model Derivative job (x-ads-force=true overwrites prior derivatives for the same URN), and inserts a row into D1 usage_log + models table.
| Name | Required | Description | Default |
|---|---|---|---|
| file_url | Yes | Publicly fetchable HTTPS URL to the 3D model file. Must be directly downloadable (no login wall, no JS redirect); the worker does a plain fetch() and streams the bytes into APS OSS. Max 100MB for direct upload. Presigned S3/GCS URLs work well. | |
| file_name | Yes | Filename including the extension. The extension is used to determine the tier (free/pro/enterprise) and is preserved in the OSS object key (prefixed with a Unix-ms timestamp). Use only ASCII + dash/underscore/dot; no path separators. | |
| project_name | No | Optional free-text label stored alongside the model row in D1 for grouping models by project. Does not affect APS storage or URN. Defaults to 'default' when omitted. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully covers side effects (non-idempotent, creates bucket, timestamped keys, derivative job with x-ads-force, D1 inserts), errors (401,403,404,409,429,5xx with guidance), rate limits, and required APS scopes. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening sentence, but it is somewhat lengthy. Error codes and side effects could be grouped slightly more concisely, but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and 3 parameters, the description covers all necessary aspects: purpose, usage, parameters, error handling, rate limits, scopes, and side effects. An agent has enough information to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 3 parameters are documented with schema coverage 100%. The description adds context beyond schema: file_url specifies 100MB limit and presigned URL support, file_name explains extension usage for tier and allowed characters, project_name notes optionality and default value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the tool's action (ingest, upload, translate), the resource (3D model from public URL), and the outputs (URN, viewer link, QR code). It lists 50+ supported formats, distinguishing it from sibling tools like get_model_metadata which handles re-translation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (publicly downloadable 3D file needing SVF2 translation) and when NOT to use (local/auth-protected files, re-translation). Suggests get_model_metadata as alternative for re-translation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
xr_launch_ar_sessionAInspect
Create a shareable WebXR AR passthrough session URL and QR code. On phone or tablet with WebXR AR support, the model is overlaid on the camera feed at the requested scale. When to use: a field user needs to walk the jobsite with a phone and see the model overlaid in-place at 1:1 scale, or drop a tabletop mini-model on a desk. When NOT to use: the target device is a Meta Quest in VR mode — use xr_launch_vr_session. The device lacks WebXR AR (desktop browser) — use get_viewer_link. APS scopes: viewables:read data:read (enforced at viewer page load, not at tool call). 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 (only at viewer page load); 403 scope or resource permission denied; 404 URN not found — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: NON-IDEMPOTENT. Each call mints a new session_id (ar_). Inserts a row into D1 usage_log read by xr_list_sessions. No APS resources are created.
| Name | Required | Description | Default |
|---|---|---|---|
| scale | No | Model placement scale. '1:1' for in-situ real-world scale, 'tabletop' for ~1:50 desk-top display, 'custom' to allow pinch-to-scale. Defaults to '1:1'. | |
| model_id | Yes | APS URN (base64url-encoded, starts with 'dXJu', unpadded) of the model to load in AR. | |
| session_name | No | Human-readable session label shown in the session list. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses non-idempotent behavior, side effects (new session_id, D1 usage log), APS scopes enforced at viewer load, rate limits, and error codes with guidance. Thoroughly covers behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, but includes verbose error detail and rate limits that could be externalized. However, it remains focused and front-loads key purpose and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 3 parameters, the description covers purpose, usage, alternatives, side effects, permissions, errors, and context. Very complete for tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond schema; it briefly mentions scale options but schema already details them. No extra value for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a shareable WebXR AR session URL and QR code, with specific use case examples. It distinguishes from sibling tools by naming alternatives (xr_launch_vr_session, get_viewer_link).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 with named alternatives (xr_launch_vr_session for VR mode, get_viewer_link for desktop), providing clear decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
xr_launch_vr_sessionAInspect
Create a shareable WebXR VR walkthrough session URL (and Meta Quest oculus:// deep link + QR code) for a translated model. The session_id is generated server-side; rendering happens in the user's Quest browser. When to use: you need to walk a client or field team through a model in immersive VR on Meta Quest 2/3/Pro. When NOT to use: the user is on a phone/tablet without a headset — use xr_launch_ar_session or get_viewer_link. The model has not finished translating — call get_model_metadata first. APS scopes: viewables:read data:read (enforced at viewer page load, not at tool call). 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 (only at viewer page load); 403 scope or resource permission denied; 404 URN not found — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: NON-IDEMPOTENT. Each call mints a new session_id (vr_). Inserts a row into D1 usage_log which is later read by xr_list_sessions. No APS resources are created.
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | Yes | APS URN (base64url-encoded, starts with 'dXJu', unpadded) of the model to load in VR. | |
| session_name | No | Human-readable session label shown in the session list. Defaults to 'VR Session' if omitted. | |
| max_participants | No | Maximum concurrent participants in multi-user mode. Integer 1-20. Defaults to 5. | |
| enable_measurements | No | Enable in-VR tape-measure tool. Defaults to true. | |
| enable_voice_annotations | No | Enable voice-note recording anchored to model elements. Defaults to false. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description comprehensively covers side effects (non-idempotent, new session_id, D1 log insertion), error codes, rate limits, and scope enforcement behavior. It even notes that APS scopes are enforced at viewer page load, not at tool call time.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (purpose, when to use, scopes, rate limits, errors, side effects). Front-loaded with the main action. Could be slightly more concise, but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, 1 required, no output schema, the description is highly complete. It covers prerequisites, alternatives, side effects, errors, rate limits, and indirect output description. No major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with each parameter having examples and descriptions. The tool description does not add any additional parameter semantics beyond the schema, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a shareable WebXR VR walkthrough session URL, deep link, and QR code for a translated model. It distinguishes itself by specifying when not to use and recommending alternatives like xr_launch_ar_session or get_viewer_link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'When to use' and 'When NOT to use' conditions, including specific alternatives and prerequisite checks (e.g., call get_model_metadata first). This gives clear guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
xr_list_sessionsAInspect
List the last 20 VR/AR sessions launched via xr_launch_vr_session and xr_launch_ar_session, sorted by creation time desc. Sourced from the D1 usage_log table; returns an empty array if D1 is unavailable or no sessions have been recorded. When to use: you want to audit who launched which XR session and when, or surface recent sessions to a user. When NOT to use: you want details (join URL, features) for a specific session — those details live inside the original launch response and are not stored beyond the log row. APS scopes: none (D1 read only). 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 (not applicable: no APS call); 403 scope or resource permission denied (not applicable); 404 not applicable; 429 rate limited — backoff and retry (worker-level only); 5xx APS upstream outage — retry with jitter (not applicable). Side effects: READ-ONLY. Idempotent.
| Name | Required | Description | Default |
|---|---|---|---|
| model_id | No | Reserved for future filtering by model URN. Currently not applied; all recent xr_* sessions are returned. | |
| session_type | No | Reserved for future filtering by session type. Currently not applied; both VR and AR sessions are returned. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: returns last 20, sorted desc, empty array if D1 unavailable, read-only, idempotent. Also covers rate limits, errors, and side effects. No annotations exist, so description fully carries the burden and does so thoroughly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than necessary but well-structured with clear sections. The core purpose is front-loaded. Every sentence provides valuable information, though some redundancy (e.g., repeating 'not applicable' for error codes) could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (list operation), the description covers return behavior, error scenarios, rate limits, side effects, and parameter explanations. Lacks an output schema, but the return value (list of sessions up to 20) is described. Complete enough for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully described in the schema (100% coverage). The description adds value by stating they are reserved for future filtering and currently not applied, which clarifies their current ineffectiveness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly lists the verb (list), resource (last 20 VR/AR sessions), and scope (sourced from D1 usage_log, sorted by creation time). It distinguishes itself from sibling launch tools by specifying it lists sessions launched via those tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'When to use' (audit, surface recent sessions) and 'When NOT to use' (if details for a specific session needed, which are in the launch response). No ambiguity about alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!